Merge branch 'master' into cn

* master: (546 commits)
  chore(deps): bump gunicorn in /tests/apps/dockerfile-release
  chore(deps): bump github.com/traefik/traefik/v2
  chore(deps): bump gunicorn from 26.0.0 to 26.1.0 in /tests/apps/multi
  chore(deps): bump gunicorn in /tests/apps/python-flask
  chore(deps): bump pygments from 2.20.0 to 2.21.0 in /docs/_build
  chore: bump herokuish to 0.11.16
  chore: bump go modules
  chore(deps): bump golang.org/x/crypto in /plugins/common
  chore(deps): bump sqlparse in /tests/apps/dockerfile-release
  chore(deps): bump helm.sh/helm/v3 in /plugins/scheduler-k3s
  chore(deps): bump golang in /tests/apps/zombies-dockerfile-no-tini
  chore(deps): bump golang in /tests/apps/go-fail-postdeploy
  chore(deps): bump golang in /tests/apps/go-fail-predeploy
  chore(deps): bump golang from 1.26.5 to 1.26.6 in /tests/apps/gogrpc
  chore(deps): bump golang in /tests/apps/zombies-dockerfile-tini
  chore(deps): bump google.golang.org/protobuf in /tests/apps/gogrpc
  fix: retire cron containers past their active deadline
  Release 0.38.27
  fix: report traefik dns-provider env vars as global keys
  fix: do not require a local image for k3s deploys
  ...

# Conflicts:
#	common.mk
#	contrib/dependencies.json

.devcontainer/devcontainer.json

@@ -31,9 +31,10 @@
   ],
   "overrideCommand": false,
   "postCreateCommand": "setup-dev-env",
+  "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"
-}
+}

.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/actions/build-image/action.yml

@@ -13,19 +13,25 @@ runs:
   using: "composite"
   steps:
     - name: download packages
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@v8
       with:
         name: build
         path: build
 
     - name: set up docker buildx
       id: buildx
-      uses: docker/setup-buildx-action@v3
+      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/dependabot.yml

@@ -134,6 +134,13 @@ updates:
     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:
@@ -182,140 +189,140 @@ updates:
       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"
+      - "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:
@@ -323,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:
@@ -336,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/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
       skip: ${{ steps.check-commit.outputs.skip }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
@@ -53,14 +53,14 @@ jobs:
     timeout-minutes: 45
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: set up qemu
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
 
       - name: set up docker buildx
         id: buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: build package
         run: ./tests/ci/setup.sh build
@@ -75,7 +75,7 @@ jobs:
           echo "matrix=$json" >> $GITHUB_OUTPUT
 
       - name: upload packages
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: build
           path: build
@@ -87,7 +87,7 @@ jobs:
     timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: build-image
         uses: ./.github/actions/build-image
@@ -97,11 +97,11 @@ jobs:
   build-image-arm64:
     name: build-image.linux/arm64
     needs: build
-    runs-on: buildjet-4vcpu-ubuntu-2204-arm
+    runs-on: ubuntu-24.04-arm
     timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: build-image
         uses: ./.github/actions/build-image
@@ -117,10 +117,10 @@ jobs:
       matrix: ${{fromJson(needs.build.outputs.matrix)}}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: download packages
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: build
           path: build
@@ -143,7 +143,7 @@ jobs:
           SYNC_GITHUB_PASSWORD: ${{ secrets.SYNC_GITHUB_PASSWORD }}
           SYNC_GITHUB_USERNAME: ${{ secrets.SYNC_GITHUB_USERNAME }}
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: test-results-${{ matrix.index }}
           path: test-results
@@ -156,10 +156,10 @@ jobs:
       fail-fast: false
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: download packages
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: build
           path: build
@@ -190,10 +190,10 @@ jobs:
       GITHUB_NODE_INDEX: ${{ matrix.index }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: download packages
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: build
           path: build
@@ -214,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@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: coverage.${{ matrix.index }}
           path: test-results/coverage
@@ -230,7 +230,7 @@ jobs:
 
     steps:
       - name: download test-results
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: test-results
 
@@ -239,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

@@ -42,7 +42,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       # workaround for https://github.com/github/codeql/issues/14235
       - name: Remove go.work file
@@ -50,7 +50,7 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3
+        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.
@@ -61,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@v3
+        uses: github/codeql-action/autobuild@v4
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -71,4 +71,4 @@ jobs:
       #    uses a compiled language
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3
+        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

@@ -16,12 +16,12 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Cloning repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
       - name: "Setup python 3.10"
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: '3.10'
 

.github/workflows/lint.yml

@@ -20,9 +20,9 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Run hadolint
-        uses: hadolint/hadolint-action@54c9adbab1582c2ef04b2016b760714a4bfde3cf
+        uses: hadolint/hadolint-action@2332a7b74a6de0dda2e2221d575162eba76ba5e5
         # v3.0.0 => 4b5806eb9c6bee4954fc0e0cc3ad6175fc9782c1
 
   markdown-lint:
@@ -30,9 +30,9 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Setup node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version: '20'
           cache: 'npm'
@@ -45,9 +45,10 @@ jobs:
   packer:
     name: packer
     runs-on: ubuntu-24.04
+    if: github.event.pull_request.user.login != 'dependabot[bot]'
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Setup packer
         uses: hashicorp/setup-packer@main
         with:
@@ -56,15 +57,9 @@ 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@v45.0.7
-        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:
@@ -72,7 +67,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Run shellcheck
         uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38
         # 1.1.0 => 94e0aab03ca135d11a35e5bfc14e6746dc56e7e9
@@ -82,9 +77,9 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Run shfmt
-        uses: luizm/action-sh-checker@17bd25a6ee188d2b91f677060038f4ba37ba14b2
+        uses: luizm/action-sh-checker@883217215b11c1fabbf00eb1a9a041f62d74c744
         # v0.5.0 => edd0e45ecff35b05f162052b50df50976c1b74fc
         env:
           SHFMT_OPTS: -l -bn -ci -i 2 -d
@@ -96,7 +91,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Run yamllint
         uses: ibiqlik/action-yamllint@2576378a8e339169678f9939646ee3ee325e845c
         # v3.1.1 => 2576378a8e339169678f9939646ee3ee325e845c

.github/workflows/release.yml

@@ -25,7 +25,7 @@ jobs:
     outputs:
       version: ${{ steps.version.outputs.version }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
@@ -34,17 +34,17 @@ jobs:
           ruby-version: 2.7
 
       - name: login to docker hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: set up qemu
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
 
       - name: set up docker buildx
         id: buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: inspect builder
         run: |
@@ -73,7 +73,7 @@ jobs:
         run: echo "version=$(cat build/next-version)" >> $GITHUB_OUTPUT
 
       - name: upload packages
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: build
           path: build
@@ -84,7 +84,7 @@ jobs:
     needs: release
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup packer
         uses: hashicorp/setup-packer@main
@@ -109,7 +109,7 @@ jobs:
           PKR_VAR_dokku_version="${VERSION:1}" make image/build/digitalocean
 
       - name: upload packages
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: digitalocean-manifest.json
           path: digitalocean-manifest.json
@@ -120,7 +120,7 @@ jobs:
     needs: release
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Bump Azure Template
         env:
           BOT_GITHUB_USERNAME: ${{ secrets.HOMEBREW_GITHUB_USERNAME }}
@@ -147,6 +147,10 @@ jobs:
           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"
@@ -154,7 +158,7 @@ jobs:
           echo "====> Running brew cleanup"
           brew cleanup || true
       - name: Brew doctor
-        run: brew doctor
+        run: brew doctor || true
       - name: Brew config
         run: brew config
       - name: Bump Homebrew Formula

Dockerfile

@@ -1,4 +1,4 @@
-FROM phusion/baseimage:noble-1.0.0
+FROM phusion/baseimage:noble-1.0.3
 
 CMD ["/sbin/my_init"]
 
@@ -15,27 +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 install -y --no-install-recommends gpg lsb-release \
+  && 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-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/ 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 \
-  && DOKKU_INIT_SYSTEM=sv 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/*
@@ -65,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

Makefile

@@ -11,7 +11,7 @@ PROCFILE_UTIL_URL ?= $(shell jq -r --arg name procfile-util  --arg arch $(TARGET
 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-24
+PREBUILT_STACK_URL ?= ccr.ccs.tencentyun.com/miaogai/herokuish:latest-24
 DOKKU_LIB_ROOT ?= /var/lib/dokku
 PLUGINS_PATH ?= ${DOKKU_LIB_ROOT}/plugins
 CORE_PLUGINS_PATH ?= ${DOKKU_LIB_ROOT}/core-plugins
@@ -190,7 +190,8 @@ docker:
 	grep -i -E "^docker" /etc/group || groupadd docker
 	usermod -aG docker dokku
 ifndef CI
-	wget -nv -O - https://get.docker.com/ | sh
+	sudo apt install docker.io
+	#wget --no-check-certificate -nv -O - https://get.docker.com/ | sh
 ifdef DOCKER_VERSION
 	apt-get -qq -y --no-install-recommends install docker-engine=${DOCKER_VERSION} || (apt-cache madison docker-engine ; exit 1)
 endif
@@ -226,3 +227,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

@@ -74,7 +74,7 @@ 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 / 24.04 (amd64/arm64) - Any currently supported release
+- 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.
@@ -85,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.35.16/bootstrap.sh
-sudo DOKKU_TAG=v0.35.16 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.

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/24.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 [11, 12], Ubuntu [20.04, 22.04, 24.04]"
+SUPPORTED_VERSIONS="Debian [11, 12, 13], Ubuntu [22.04, 24.04]"
 
 log-fail() {
   declare desc="log fail formatter"
@@ -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" "20.04" "22.04" "24.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
 
@@ -188,17 +209,17 @@ install-dokku-from-deb-package() {
   fi
 
   if [[ "$DOKKU_DISTRO" == "ubuntu" ]]; then
-    OS_IDS=("focal" "jammy" "noble")
+    OS_IDS=("jammy" "noble")
     if ! in-array "$OS_ID" "${OS_IDS[@]}"; then
       OS_ID="noble"
     fi
   elif [[ "$DOKKU_DISTRO" == "debian" ]]; then
-    OS_IDS=("bullseye" "bookworm")
+    OS_IDS=("bullseye" "bookworm" "trixie")
     if ! in-array "$OS_ID" "${OS_IDS[@]}"; then
       OS_ID="bookworm"
     fi
   elif [[ "$DOKKU_DISTRO" == "raspbian" ]]; then
-    OS_IDS=("bullseye" "bookworm")
+    OS_IDS=("bullseye" "bookworm" "trixie")
     if ! in-array "$OS_ID" "${OS_IDS[@]}"; then
       OS_ID="bookworm"
     fi

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.23.0
+BUILD_IMAGE := hub.diyla.com/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)
@@ -19,6 +19,7 @@ build-in-docker: clean
 		-v $(GO_MOD_CACHE):/go/pkg/mod \
 		-e PLUGIN_NAME=$(PLUGIN_NAME) \
 		-e GO111MODULE=on \
+		-e GOPROXY=https://goproxy.cn,direct \
 		-w $(GO_REPO_ROOT)/plugins/$(PLUGIN_NAME) \
 		$(BUILD_IMAGE) \
 		bash -c "GO_ARGS='$(GO_ARGS)' CGO_ENABLED=0 GOOS=linux GOARCH=$(GOARCH) GOWORK=off make -j4 $(GO_PLUGIN_MAKE_TARGET)" || exit $$?

contrib/build-docs

@@ -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

@@ -7,7 +7,7 @@ ARG WORKDIR=/go/src/github.com/dokku/dokku
 
 WORKDIR ${WORKDIR}
 
-RUN wget -qO /tmp/go${GOLANG_VERSION}.linux.tar.gz "https://storage.googleapis.com/golang/go${GOLANG_VERSION}.linux-$(dpkg --print-architecture).tar.gz" \
+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
@@ -23,7 +23,7 @@ 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
@@ -38,7 +38,7 @@ RUN PLUGIN_MAKE_TARGET=${PLUGIN_MAKE_TARGET} \
   make version copyfiles \
   && make deb-dokku
 
-FROM builder as arm64
+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

contrib/dependencies.json

@@ -2,95 +2,103 @@
   "dependencies": [
     {
       "name": "docker-container-healthchecker",
-      "version": "0.11.0",
+      "version": "0.16.0",
       "urls": {
-        "amd64": "https://github.com/dokku/docker-container-healthchecker/releases/download/v0.11.0/docker-container-healthchecker-linux-amd64",
-        "arm64": "https://github.com/dokku/docker-container-healthchecker/releases/download/v0.11.0/docker-container-healthchecker-linux-arm64"
+        "amd64": "https://hub.diyla.com/https://github.com/dokku/docker-container-healthchecker/releases/download/v0.16.0/docker-container-healthchecker-linux-amd64",
+        "arm64": "https://hub.diyla.com/https://github.com/dokku/docker-container-healthchecker/releases/download/v0.16.0/docker-container-healthchecker-linux-arm64"
       }
     },
     {
       "name": "docker-image-labeler",
-      "version": "0.8.0",
+      "version": "0.10.0",
       "urls": {
-        "amd64": "https://github.com/dokku/docker-image-labeler/releases/download/v0.8.0/docker-image-labeler-linux-amd64",
-        "arm64": "https://github.com/dokku/docker-image-labeler/releases/download/v0.8.0/docker-image-labeler-linux-arm64"
+        "amd64": "https://hub.diyla.com/https://github.com/dokku/docker-image-labeler/releases/download/v0.10.0/docker-image-labeler-linux-amd64",
+        "arm64": "https://hub.diyla.com/https://github.com/dokku/docker-image-labeler/releases/download/v0.10.0/docker-image-labeler-linux-arm64"
       }
     },
     {
       "name": "lambda-builder",
-      "version": "0.8.0",
+      "version": "0.9.4",
       "urls": {
-        "amd64": "https://github.com/dokku/lambda-builder/releases/download/v0.8.0/lambda-builder-linux-amd64",
-        "arm64": "https://github.com/dokku/lambda-builder/releases/download/v0.8.0/lambda-builder-linux-arm64"
+        "amd64": "https://hub.diyla.com/https://github.com/dokku/lambda-builder/releases/download/v0.9.4/lambda-builder-linux-amd64",
+        "arm64": "https://hub.diyla.com/https://github.com/dokku/lambda-builder/releases/download/v0.9.4/lambda-builder-linux-arm64"
       }
     },
     {
       "name": "netrc",
-      "version": "0.10.0",
+      "version": "0.11.1",
       "urls": {
-        "amd64": "https://github.com/dokku/netrc/releases/download/v0.10.0/netrc-linux-amd64",
-        "arm64": "https://github.com/dokku/netrc/releases/download/v0.10.0/netrc-linux-arm64"
+        "amd64": "https://hub.diyla.com/https://github.com/dokku/netrc/releases/download/v0.11.1/netrc-linux-amd64",
+        "arm64": "https://hub.diyla.com/https://github.com/dokku/netrc/releases/download/v0.11.1/netrc-linux-arm64"
+      }
+    },
+    {
+      "name": "pack",
+      "version": "0.40.9",
+      "urls": {
+        "amd64": "https://hub.diyla.com/https://github.com/buildpacks/pack/releases/download/v0.40.9/pack-v0.40.9-linux.tgz",
+        "arm64": "https://hub.diyla.com/https://github.com/buildpacks/pack/releases/download/v0.40.9/pack-v0.40.9-linux-arm64.tgz"
       }
     },
     {
       "name": "procfile-util",
-      "version": "0.19.0",
+      "version": "0.20.8",
       "urls": {
-        "amd64": "https://github.com/dokku/procfile-util/releases/download/v0.19.0/procfile-util-linux-amd64",
-        "arm64": "https://github.com/dokku/procfile-util/releases/download/v0.19.0/procfile-util-linux-arm64"
+        "amd64": "https://hub.diyla.com/https://github.com/dokku/procfile-util/releases/download/v0.20.8/procfile-util-linux-amd64",
+        "arm64": "https://hub.diyla.com/https://github.com/dokku/procfile-util/releases/download/v0.20.8/procfile-util-linux-arm64"
       }
     },
     {
       "name": "sshcommand",
-      "version": "0.19.0",
+      "version": "0.20.2",
       "urls": {
-        "amd64": "https://github.com/dokku/sshcommand/releases/download/v0.19.0/sshcommand",
-        "arm64": "https://github.com/dokku/sshcommand/releases/download/v0.19.0/sshcommand"
+        "amd64": "https://hub.diyla.com/https://github.com/dokku/sshcommand/releases/download/v0.20.2/sshcommand",
+        "arm64": "https://hub.diyla.com/https://github.com/dokku/sshcommand/releases/download/v0.20.2/sshcommand"
       }
     }
   ],
   "predependencies": [
     {
       "name": "gliderlabs-sigil",
-      "version": "0.11.0",
+      "version": "0.12.1",
       "urls": {
-        "amd64": "https://github.com/gliderlabs/sigil/releases/download/v0.11.0/sigil-linux-amd64",
-        "arm64": "https://github.com/gliderlabs/sigil/releases/download/v0.11.0/sigil-linux-arm64"
+        "amd64": "https://hub.diyla.com/https://github.com/gliderlabs/sigil/releases/download/v0.12.1/sigil-linux-amd64",
+        "arm64": "https://hub.diyla.com/https://github.com/gliderlabs/sigil/releases/download/v0.12.1/sigil-linux-arm64"
       }
     },
     {
       "name": "plugn",
-      "version": "0.15.3",
+      "version": "0.17.1",
       "urls": {
-        "amd64": "https://github.com/dokku/plugn/releases/download/v0.15.3/plugn-linux-amd64",
-        "arm64": "https://github.com/dokku/plugn/releases/download/v0.15.3/plugn-linux-arm64"
+        "amd64": "https://hub.diyla.com/https://github.com/dokku/plugn/releases/download/v0.17.1/plugn-linux-amd64",
+        "arm64": "https://hub.diyla.com/https://github.com/dokku/plugn/releases/download/v0.17.1/plugn-linux-arm64"
       }
     }
   ],
   "recommendations": [
     {
       "name": "dokku-event-listener",
-      "version": "0.17.0",
+      "version": "0.20.1",
       "urls": {
-        "amd64": "https://github.com/dokku/dokku-event-listener/releases/download/v0.17.0/dokku-event-listener-linux-amd64",
-        "arm64": "https://github.com/dokku/dokku-event-listener/releases/download/v0.17.0/dokku-event-listener-linux-arm64"
+        "amd64": "https://hub.diyla.com/https://github.com/dokku/dokku-event-listener/releases/download/v0.20.1/dokku-event-listener-linux-amd64",
+        "arm64": "https://hub.diyla.com/https://github.com/dokku/dokku-event-listener/releases/download/v0.20.1/dokku-event-listener-linux-arm64"
       }
     },
     {
       "name": "dokku-update",
-      "version": "0.9.4",
+      "version": "0.10.0",
       "urls": {
-        "amd64": "https://github.com/dokku/dokku-update/releases/download/v0.9.4/dokku-update",
-        "arm64": "https://github.com/dokku/dokku-update/releases/download/v0.9.4/dokku-update"
+        "amd64": "https://hub.diyla.com/https://github.com/dokku/dokku-update/releases/download/v0.10.0/dokku-update",
+        "arm64": "https://hub.diyla.com/https://github.com/dokku/dokku-update/releases/download/v0.10.0/dokku-update"
       }
     },
     {
       "name": "herokuish",
-      "version": "0.10.2",
+      "version": "0.11.16",
       "urls": {
-        "amd64": "https://github.com/gliderlabs/herokuish/releases/download/v0.10.2/herokuish_0.10.2_linux_x86_64.tgz",
-        "arm64": "https://github.com/gliderlabs/herokuish/releases/download/v0.10.2/herokuish_0.10.2_linux_x86_64.tgz"
+        "amd64": "https://hub.diyla.com/https://github.com/gliderlabs/herokuish/releases/download/v0.11.16/herokuish_0.11.16_linux_x86_64.tgz",
+        "arm64": "https://hub.diyla.com/https://github.com/gliderlabs/herokuish/releases/download/v0.11.16/herokuish_0.11.16_linux_x86_64.tgz"
       }
     }
   ]
-}
+}

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"
@@ -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,6 +138,11 @@ 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
@@ -111,14 +151,28 @@ main() {
   if [[ -z "$APP" ]]; 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,8 +238,13 @@ 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
   if [[ -n "$@" ]] && [[ -n "$APP" ]]; then

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

@@ -355,7 +355,7 @@ function checkFirewall {
   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++))

contrib/release-dokku

@@ -134,7 +134,7 @@ fn-publish-package() {
   [[ "$RELEASE_TYPE" == "raspbian" ]] && DIST=raspbian
 
   if [[ "$RELEASE_TYPE" == "raspbian" ]]; then
-    OS_IDS=("bullseye" "bookworm")
+    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"
@@ -144,7 +144,7 @@ fn-publish-package() {
       fi
     done
   elif [[ "$DIST" == "ubuntu" ]]; then
-    OS_IDS=("focal" "jammy" "noble")
+    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"
@@ -155,7 +155,7 @@ fn-publish-package() {
     done
 
     DIST=debian
-    OS_IDS=("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"
@@ -183,9 +183,9 @@ fn-replace-version() {
 
 fn-repo-merged-requests() {
   declare desc="Retrieves all pull request ids since a given release of dokku"
-  declare TAG="$1" IS_PATCH="$2"
+  declare CURRENT_VERSION="$1" NEXT_VERSION="$2" IS_PATCH="$3"
   if [[ "$IS_PATCH" == "true" ]]; then
-    git log "v${TAG}..HEAD" --oneline | grep "Merge pull request" | cut -d' ' -f 5 | cut -d '#' -f2
+    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
@@ -250,13 +250,13 @@ fn-repo-update-history-and-commit() {
   declare desc="Updates the history file and commits the changes"
   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" "$IS_PATCH"); 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
@@ -295,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
@@ -314,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"

contrib/update-deb-dependencies

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 import json
+import re
 
 
 def main():
@@ -18,11 +19,9 @@ def main():
         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):
-                if name in line:
-                    control_lines[i] = control_lines[i].replace(
-                        name, f"{name} (>= {version})"
-                    )
+                control_lines[i] = pattern.sub(f"{name} (>= {version})", line)
 
     with open("debian/control", mode="w", encoding="utf-8") as handle:
         handle.writelines(control_lines)

debian/config

@@ -14,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.35.16
+Version: 0.38.27
 Section: web
 Priority: optional
 Architecture: amd64
-Depends: apache2-utils, locales, git, cpio, cron, curl, 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-buildx-plugin | moby-buildx, docker-container-healthchecker, docker-image-labeler, lambda-builder, net-tools, netrc, parallel, procfile-util, rsync, dos2unix, jq, unzip, util-linux
+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, nginx (>= 1.8.0) | openresty, bind9-dnsutils, debconf, plugn, sudo, python3, rsyslog
+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

@@ -24,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
@@ -101,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"
@@ -128,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
@@ -138,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/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/my_init.d/10_dokku_init

@@ -35,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
@@ -86,7 +89,7 @@ main() {
   fi
 
   # run core install triggers to force create any folders that may be missing
-  dokku plugin:install --core
+  dokku plugin:install
 
   if [[ -n "$DOKKU_HOSTNAME" ]]; then
     echo "dokku dokku/hostname string $DOKKU_HOSTNAME" | debconf-set-selections

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/sudoers.d/dokku-docker

@@ -1 +1 @@
-dokku    ALL=NOPASSWD:SETENV:/usr/bin/docker,/usr/bin/docker-container-healthchecker,/usr/bin/docker-image-labeler,/usr/bin/pack
+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/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.13.2-alpine
+FROM python:3.15.0rc1-alpine
 
 WORKDIR /usr/src/app
 

docs/_build/requirements.txt

@@ -1,23 +1,23 @@
-beautifulsoup4==4.13.3
-click==8.1.8
+beautifulsoup4==4.15.0
+click==8.4.2
 ghp-import==2.1.0
-importlib-metadata==8.6.1
-Jinja2==3.1.5
-Markdown>=3.2.1,<3.8
-MarkupSafe==3.0.2
+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.6.1
 mkdocs-exclude==1.0.2
-mkdocs-material==9.6.7
+mkdocs-material==9.7.7
 mkdocs-material-extensions==1.3.1
-packaging==24.2
-Pygments==2.19.1
-pymdown-extensions==10.14.3
-pyparsing==3.2.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.2
-pyyaml_env_tag==0.1
+PyYAML==6.0.3
+pyyaml_env_tag==1.1
 six==1.17.0
-soupsieve==2.6
+soupsieve==2.9.2
 watchdog==6.0.0
-zipp==3.21.0
+zipp==4.1.0

docs/advanced-usage/backup-recovery.md

@@ -96,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

@@ -101,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
@@ -122,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
 ```
 

docs/advanced-usage/docker-options.md

@@ -4,10 +4,11 @@
 > New as of 0.3.17
 
 ```
-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 app
-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
 ```
 
 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.
@@ -37,6 +38,16 @@ More information on supported Docker options can be found [here](https://docs.do
 
 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.
 
+#### Scheduler support
+
+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.
+
+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
+dokku docker-options:add node-js-app deploy "--sysctl net.ipv4.ip_unprivileged_port_start=1024"
+```
+
 #### Mounting volumes and host directories
 
 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.
@@ -57,11 +68,31 @@ Multiple phases can be specified by using a comma when specifying phases:
 dokku docker-options:add node-js-app deploy,run "--ulimit nofile=12"
 ```
 
-The `docker-options:add` does not support setting multiple options in a single call. To specify multiple options, call `docker-options:add` multiple times.
+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"
-dokku docker-options:add node-js-app deploy "--shm-size 256m"
+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
@@ -69,7 +100,7 @@ dokku docker-options:add node-js-app deploy "--shm-size 256m"
 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"
+dokku docker-options:remove node-js-app run "--ulimit nofile=12"
 ```
 
 Multiple phases can be specified by using a comma when specifying phases:
@@ -78,11 +109,17 @@ Multiple phases can be specified by using a comma when specifying phases:
 dokku docker-options:remove node-js-app deploy,run "--ulimit nofile=12"
 ```
 
-The `docker-options:remove` does not support setting multiple options in a single call. To specify multiple options, call `docker-options:remove` multiple times.
+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"
-dokku docker-options:remove node-js-app deploy "--shm-size 256m"
+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
@@ -160,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/persistent-storage.md

@@ -1,24 +1,41 @@
 # Persistent Storage
 
 > [!IMPORTANT]
-> New as of 0.5.0
+> 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
 
@@ -44,9 +61,23 @@ 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"
   }
 ]
 ```
@@ -74,17 +105,135 @@ By default, permissions are set for usage with Herokuish buildpacks. These permi
     - 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/builder` 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.
+- `--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.
 
+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
 
 Dokku supports mounting both explicit host paths as well as docker volumes via the `storage:mount` command. This takes two arguments, an app name and a `host-path:container-path` or `docker-volume:container-path` combination.
@@ -103,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
@@ -127,6 +287,65 @@ 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]
@@ -172,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
@@ -214,3 +487,13 @@ By default, Dokku will execute your buildpack app processes as the `herokuishuse
 > 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

@@ -6,10 +6,10 @@
 ```
 plugin:disable <name>                    # Disable an installed plugin (third-party only)
 plugin:enable <name>                     # Enable a previously disabled plugin
-plugin:install [--core|--git-url] [--committish branch|commit|tag] [--name custom-plugin-name]           # Optionally download git-url (and pin to the specified branch/commit/tag) & run install trigger for active plugins (or only core ones)
+plugin: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 [branch|commit|tag]] # Optionally update named plugin from git (and pin to the specified branch/commit/tag) & run update trigger for active plugins
@@ -36,37 +36,70 @@ dokku plugin:list
 
 ```
 plugn: dev
-  00_dokku-standard    0.35.16 enabled    dokku core standard plugin
-  20_events            0.35.16 enabled    dokku core events logging plugin
-  app-json             0.35.16 enabled    dokku core app-json plugin
-  apps                 0.35.16 enabled    dokku core apps plugin
-  build-env            0.35.16 enabled    dokku core build-env plugin
-  buildpacks           0.35.16 enabled    dokku core buildpacks plugin
-  certs                0.35.16 enabled    dokku core certificate management plugin
-  checks               0.35.16 enabled    dokku core checks plugin
-  common               0.35.16 enabled    dokku core common plugin
-  config               0.35.16 enabled    dokku core config plugin
-  docker-options       0.35.16 enabled    dokku core docker-options plugin
-  domains              0.35.16 enabled    dokku core domains plugin
-  enter                0.35.16 enabled    dokku core enter plugin
-  git                  0.35.16 enabled    dokku core git plugin
-  logs                 0.35.16 enabled    dokku core logs plugin
-  network              0.35.16 enabled    dokku core network plugin
-  nginx-vhosts         0.35.16 enabled    dokku core nginx-vhosts plugin
-  plugin               0.35.16 enabled    dokku core plugin plugin
-  proxy                0.35.16 enabled    dokku core proxy plugin
-  ps                   0.35.16 enabled    dokku core ps plugin
-  repo                 0.35.16 enabled    dokku core repo plugin
-  resource             0.35.16 enabled    dokku core resource plugin
-  scheduler-docker-local 0.35.16 enabled    dokku core scheduler-docker-local plugin
-  shell                0.35.16 enabled    dokku core shell plugin
-  ssh-keys             0.35.16 enabled    dokku core ssh-keys plugin
-  storage              0.35.16 enabled    dokku core storage plugin
-  tags                 0.35.16 enabled    dokku core tags plugin
-  tar                  0.35.16 enabled    dokku core tar plugin
-  trace                0.35.16 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
 ```
 
+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.
 
@@ -128,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

docs/advanced-usage/registry-management.md

@@ -4,9 +4,10 @@
 > 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.
@@ -15,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.
@@ -104,13 +146,27 @@ 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 globally with the `image-repo-template` property:
+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.
+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
 
@@ -136,6 +192,10 @@ dokku registry:set node-js-app push-on-release
 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.
@@ -166,3 +226,18 @@ 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/resource-management.md

@@ -32,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
 
@@ -120,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.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.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/file-formats/app-json.md

@@ -5,11 +5,30 @@
 > [!IMPORTANT]
 > While the `app.json` format used by Dokku is based on the one [supported by Heroku](https://devcenter.heroku.com/articles/app-json-schema), not all Heroku functionality is supported by Dokku.
 
+## Buildpacks
+
+```json
+{
+  "buildpacks": [
+    {
+      "url": "heroku/python"
+    },
+    {
+      "url": "https://github.com/heroku/heroku-buildpack-nodejs.git"
+    }
+  ]
+}
+```
+
+(list, optional) A list of buildpacks to use when deploying the app. Each entry is an object with a `url` property. Buildpacks specified via the `buildpacks:add` or `buildpacks:set` commands take precedence over those specified in `app.json`. Buildpack URLs may use the shorthand format (e.g., `heroku/python`) which will be expanded to the full GitHub URL.
+
+- `url`: (string, required) The URL or shorthand reference of the buildpack.
+
 ## Cron
 
 ```json
 {
-  "crons": [
+  "cron": [
     {
       "command": "echo 'hello'",
       "schedule": "0 1 * * *"
@@ -21,7 +40,106 @@
 (list, optional) A list of cron resources. Keys are the names of the process types. The values are an object containing one or more of the following properties:
 
 - `command`: (string, required)
+- `maintenance`: (boolean, optional)
 - `schedule`: (string, required)
+- `concurrency_policy`: (string, optional, default: `allow`, options: `allow`, `forbid`, `replace`)
+
+## Env
+
+```json
+{
+  "env": {
+    "SIMPLE_VAR": "default_value",
+    "SECRET_KEY": {
+      "description": "A secret key for signing tokens",
+      "generator": "secret"
+    },
+    "DATABASE_URL": {
+      "description": "PostgreSQL connection string",
+      "required": true
+    },
+    "OPTIONAL_VAR": {
+      "description": "An optional configuration value",
+      "value": "default",
+      "required": false
+    },
+    "SYNC_VAR": {
+      "description": "A variable that updates on every deploy",
+      "value": "synced_value",
+      "sync": true
+    }
+  }
+}
+```
+
+(object, optional) A key-value object for environment variable configuration. Keys are the variable names. Values can be either a string (used as the default value) or an object with the following properties:
+
+- `description`: (string, optional) Human-readable explanation of the variable's purpose
+- `value`: (string, optional) Default value for the variable
+- `required`: (boolean, optional, default: `true`) Whether the variable must have a value
+- `generator`: (string, optional) Function to generate the value. Currently only `"secret"` is supported, which generates a 64-character cryptographically secure hex string
+- `sync`: (boolean, optional, default: `false`) If `true`, the value will be set on every deploy, overwriting any existing value
+
+### Behavior
+
+Environment variables from `app.json` are processed during the first deploy, before the predeploy script runs. The behavior depends on the variable configuration:
+
+1. **Variables with `value` or simple string**: The default value is set if the variable doesn't already exist
+2. **Variables with `generator: "secret"`**: A random 64-character hex string is generated if the variable doesn't exist
+3. **Required variables without a value or generator**: If a TTY is available, the user is prompted for a value. Otherwise, the deploy fails with an error
+4. **Optional variables without a value**: Skipped silently if no TTY is available
+
+On subsequent deploys:
+- Variables are NOT re-set unless `sync: true` is specified
+- Variables with `sync: true` are always set to their configured value, overwriting any manual changes
+- Variables that already have values are not modified
+
+### Examples
+
+**Simple default value:**
+```json
+{
+  "env": {
+    "WEB_CONCURRENCY": "5"
+  }
+}
+```
+
+**Generated secret (recommended for API keys, tokens, etc.):**
+```json
+{
+  "env": {
+    "SECRET_KEY_BASE": {
+      "description": "Base secret for session encryption",
+      "generator": "secret"
+    }
+  }
+}
+```
+
+**Required variable that must be provided:**
+```json
+{
+  "env": {
+    "DATABASE_URL": {
+      "description": "PostgreSQL connection URL",
+      "required": true
+    }
+  }
+}
+```
+
+**Variable that stays in sync with app.json:**
+```json
+{
+  "env": {
+    "FEATURE_FLAGS": {
+      "value": "new_ui,dark_mode",
+      "sync": true
+    }
+  }
+}
+```
 
 ## Formation
 
@@ -41,6 +159,7 @@
 - `autoscaling` (map of string to object, optional) autoscaling rules. See the autoscaling section for more details
 - `max_parallel`: (int, optional) number of instances to deploy in parallel at a given time
 - `quantity`: (int, optional) number of processes to maintain. Default 1 for web processes, 0 for all others.
+- `service`: (map of string to oject, optional) governs how non-web processes are exposed as services on the network
 
 ### Autoscaling
 
@@ -80,6 +199,24 @@ An autoscaling trigger consists of the following properties:
 - `type`: (string, optional)
 - `metadata`: (object, optional)
 
+### Service
+
+```json
+{
+  "formation": {  
+    "internal-web": {
+      "service": {
+        "exposed": true
+      }
+    }
+  }
+}
+```
+
+(object, optional) A key-value object specifying how to expose non-web processes as services.
+
+- `service`: (boolean, optional) Whether to expose a process as a network service. The `PORT` variable will be set to 5000.
+
 ## Healthchecks
 
 ```json
@@ -151,3 +288,14 @@ An autoscaling trigger consists of the following properties:
     - Example use-cases
         - Setting up OAuth clients and DNS
         - Loading seed/test data into the app’s test database
+
+## Properties
+
+### Settable properties
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `app-json:report`. The JSON keys emitted by `app-json:report --format json` are the same names with the leading `--app-json-` stripped (e.g. `appjson-path`, `global-appjson-path`, `computed-appjson-path`). Legacy keys with the `app-json-` prefix 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 |
+|---|---|---|---|---|
+| `appjson-path` | app + global | `app.json` | `--app-json-appjson-path`, `--app-json-global-appjson-path`, `--app-json-computed-appjson-path` | Path within the app to the `app.json` manifest, relative to the build root |

docs/appendices/file-formats/nginx-conf-sigil.md

@@ -1,3 +1,65 @@
 # nginx.conf.sigil
 
 The `nginx.conf.sigil` file is used to configure the nginx server for an application. The default template can be found [here](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil). Dokku uses a tool named [sigil](https://github.com/gliderlabs/sigil) to generate the nginx configuration based on the template provided.
+
+## Validation
+
+A custom `nginx.conf.sigil` is pre-validated at the start of every deploy, immediately after it is extracted from the source tree and before the build phase runs. Pre-validation renders the template via sigil with the same parameters used at deploy time, wraps the rendered config in a minimal `events`/`http` scaffold, and runs `nginx -t` against the result. The deploy is aborted if either the sigil render or the `nginx -t` check fails, so build work is not wasted on a syntactically invalid template. When no app listeners exist yet (typical for first deploys), pre-validation injects a placeholder `127.0.0.1:5000` listener for `DOKKU_APP_WEB_LISTENERS` so that the rendered upstream block has a static server entry and `nginx -t` does not bail out on "host not found in upstream".
+
+Pre-validation is skipped when the proxy type is not `nginx` or when `disable-custom-config` is set to `true` for the app.
+
+### Custom nginx modules
+
+Pre-validation runs `nginx -t` against a minimal wrapper config that does _not_ include the top-level `load_module` directives from the global `/etc/nginx/nginx.conf`. A `nginx.conf.sigil` that uses a directive provided by a dynamically loaded module - such as `image_filter`, provided by the [ngx_http_image_filter_module](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html) - therefore fails pre-validation with an `unknown directive` error, even though `nginx -t` succeeds against the real server config where the module is loaded.
+
+The `load_module` directive cannot be added to the app's `nginx.conf.sigil` to work around this, as that file is included inside the `http { }` block while `load_module` is only valid in nginx's top-level main context.
+
+To make pre-validation aware of a module, override the wrapper template used for validation. The [`nginx-app-template-source`](/docs/development/plugin-triggers.md#nginx-app-template-source) trigger returns the path to the `sigil` template used to generate a given nginx configuration file, and its `validate-config` template type controls the pre-validation wrapper. Create a [custom plugin](/docs/development/plugin-creation.md) that implements the trigger and returns a `validate.conf.sigil` that adds the required `load_module` line at the top of the wrapper.
+
+The trigger file (named `nginx-app-template-source` and marked executable):
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+
+APP="$1"
+TEMPLATE_TYPE="$2"
+if [[ "$TEMPLATE_TYPE" == "validate-config" ]]; then
+  echo "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/validate.conf.sigil"
+fi
+```
+
+The custom `validate.conf.sigil`, which is the [default wrapper](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/validate.conf.sigil) with the required `load_module` line added at the top. Use the same `load_module` line that the host's global `/etc/nginx/nginx.conf` uses:
+
+```
+load_module modules/ngx_http_image_filter_module.so;
+events { worker_connections 768; }
+http {
+  access_log off;
+  error_log /dev/null;
+  include {{ $.NGINX_CONF }};
+}
+```
+
+The same override also governs the standalone `dokku nginx:validate-config` command, which renders the `validate-config` template as well.
+
+## HTTP/2
+
+nginx 1.25.1 deprecated the `http2` parameter on the `listen` directive in favor of a standalone `http2 on;` directive. Custom `nginx.conf.sigil` templates that hardcode `listen ... ssl http2;` will produce `nginx: [warn] the "listen ... http2" directive is deprecated` warnings when run against nginx 1.25.1 or newer.
+
+Dokku exposes the `HTTP2_DIRECTIVE_SUPPORTED` template variable, set to `"true"` when the host nginx is 1.25.1 or newer, so a single template can render the correct syntax against either version. The default template uses this pattern:
+
+```
+{{ if eq $.HTTP2_DIRECTIVE_SUPPORTED "true" }}
+listen      [{{ $.NGINX_BIND_ADDRESS_IP6 }}]:{{ $listen_port }} ssl;
+listen      {{ if $.NGINX_BIND_ADDRESS_IP4 }}{{ $.NGINX_BIND_ADDRESS_IP4 }}:{{end}}{{ $listen_port }} ssl;
+http2 on;
+{{ else }}
+listen      [{{ $.NGINX_BIND_ADDRESS_IP6 }}]:{{ $listen_port }} ssl http2;
+listen      {{ if $.NGINX_BIND_ADDRESS_IP4 }}{{ $.NGINX_BIND_ADDRESS_IP4 }}:{{end}}{{ $listen_port }} ssl http2;
+{{ end }}
+```
+
+Dokku logs a deprecation warning during deploys when a custom template still uses the `listen ... http2` form, so the offending template can be located via the deploy output.

docs/appendices/file-formats/railpack-json.md

@@ -0,0 +1,3 @@
+# railpack.json
+
+The `railpack.json` file is used to configure an application when built with the `railpack` builder. Please refer to the [railpack.json documentation](https://railpack.com/config/file) for more information.

docs/assets/favicons/browserconfig.xml

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

docs/assets/favicons/manifest.json

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

docs/assets/style.css

@@ -25,9 +25,9 @@
 
   /* Avatar section darkmode fade */
   --avatar-before-gradient: rgba(0, 0, 0, 0) linear-gradient(90deg, white 2.52%, rgba(255, 255, 255, 0) 100%) repeat scroll 0% 0%;
-  --avatar-darkmode-before-gradient: rgba(0, 0, 0, 0) linear-gradient(90deg, #043791 2.52%, rgba(255, 255, 255, 0) 100%) repeat scroll 0% 0%;
+  --avatar-darkmode-before-gradient: rgba(0, 0, 0, 0) linear-gradient(90deg, #0.38.27 2.52%, rgba(255, 255, 255, 0) 100%) repeat scroll 0% 0%;
   --avatar-after-gradient: rgba(0, 0, 0, 0) linear-gradient(270deg, white 2.52%, rgba(255, 255, 255, 0) 100%) repeat scroll 0% 0%;
-  --avatar-darkmode-after-gradient: rgba(0, 0, 0, 0) linear-gradient(270deg, #043791 2.52%, rgba(255, 255, 255, 0) 100%) repeat scroll 0% 0%;
+  --avatar-darkmode-after-gradient: rgba(0, 0, 0, 0) linear-gradient(270deg, #0.38.27 2.52%, rgba(255, 255, 255, 0) 100%) repeat scroll 0% 0%;
 }
 
 body {
@@ -1191,15 +1191,15 @@ ul.fas li .fa-large:before {
 
   .getting-started::after {
     background: linear-gradient(0deg, rgba(52, 52, 87, 0.2) -40.97%, rgba(0, 0, 0, 0) 103.19%),
-      #043791;
+      #0.38.27;
   }
 
   .tab-content {
-    background: #043791;
+    background: #0.38.27;
   }
 
   .nav-tabs {
-    background: #043791;
+    background: #0.38.27;
   }
 
   .powered-by_brands {

docs/assets/versions.json

@@ -32,6 +32,9 @@
     "0.32.4",
     "0.33.9",
     "0.34.9",
-    "0.35.16"
+    "0.35.20",
+    "0.36.11",
+    "0.37.10",
+    "0.38.27"
   ]
 }

docs/community/clients.md

@@ -28,26 +28,6 @@ gem install dokku-cli
 
 See [documentation here](https://github.com/SebastianSzturo/dokku-cli) for more information.
 
-## (ruby) DokkuClient
-
-DokkuClient is another rubygem that acts as a client for your Dokku installation with built-in support for certain external plugins. You can install it via the following shell command (assuming you have ruby and rubygems installed):
-
-```shell
-gem install dokku_client
-```
-
-See [documentation here](https://github.com/netguru/dokku_client) for more information.
-
-## (ruby) Dokkufy
-
-Dokkufy is a rubygem that handles automation of certain tasks, such as Dokku setup, plugin installation, etc. You can install it via the following shell command (assuming you have ruby and rubygems installed):
-
-```shell
-gem install dokkufy
-```
-
-See [documentation here](https://github.com/cbetta/dokkufy) for more information.
-
 ## (ruby) Dockland
 
 Dockland is a rubygem that acts as a client for your Dokku installation. You can install it via the following shell command (assuming you have ruby and rubygems installed):

docs/community/plugins.md

@@ -104,6 +104,7 @@ The following plugins are available and provided by Dokku maintainers.  Please f
 | [InfluxDB](https://github.com/basgys/dokku-influxdb)                                              | [basgys][]            | 0.4.x                 |
 | [RethinkDB](https://github.com/stuartpb/dokku-rethinkdb-plugin)                                   | [stuartpb][]          | 0.3.x                 |
 | [Headless Chrome](https://github.com/lazyatom/dokku-chrome)                                       | [lazyatom][]          | 0.8.1+                |
+| [HTTP OAuth](https://github.com/cheif/dokku-http-oauth)                                           | [cheif][]             | 0.4.0+                |
 
 ### Plugins Implementing New Dokku Functionality
 
@@ -113,6 +114,7 @@ The following plugins are available and provided by Dokku maintainers.  Please f
 | [APT](https://github.com/dokku-community/dokku-apt)                                               | [dokku-community][]   | 0.18.x+               |
 | [Auto Sync](https://github.com/IdeaSynthesis/dokku-autosync)<sup>1</sup>                          | [fomojola][]          | 0.8.1+                |
 | [Deploy Webhook](https://github.com/IdeaSynthesis/dokku-deploy-webhook)<sup>2</sup>               | [fomojola][]          | 0.8.1+                |
+| [DNS](https://github.com/deanmarano/dokku-dns)                                                    | [deanmarano][]        | 0.31.0+               |
 | [Docker auto persist volumes](https://github.com/Flink/dokku-docker-auto-volumes)                 | [flink][]             | 0.4.0+                |
 | [Docker Direct](https://github.com/dokku-community/dokku-docker-direct)                           | [josegonzalez][]      | 0.4.0+                |
 | [Dokku Clone](https://github.com/crisward/dokku-clone)                                            | [crisward][]          | 0.4.0+                |
@@ -123,7 +125,6 @@ The following plugins are available and provided by Dokku maintainers.  Please f
 | [Host post-build command hook](https://github.com/baikunz/dokku-post-deploy-script)               | [baikunz][]           | 0.4.0+                |
 | [Host pre-build command hook](https://github.com/fteychene/dokku-build-hook)                      | [fteychene][]         | 0.4.0+                |
 | [Hostname](https://github.com/michaelshobbs/dokku-hostname)                                       | [michaelshobbs][]     | 0.4.0+                |
-| [Hostname](https://github.com/michaelshobbs/dokku-hostname)                                       | [michaelshobbs][]     | 0.4.0+                |
 | [HTTP Auth Secure Apps](https://github.com/matto1990/dokku-secure-apps)                           | [matto1990][]         | 0.4.0+                |
 | [Image Size Limit](https://github.com/Tashows/dokku-image-size-limit)                             | [Tashows][]           |                       |
 | [Litestream](https://github.com/AxelTheGerman/dokku-litestream)<sup>4</sup>                       | [AxelTheGerman][]     | 0.27.0+               |
@@ -267,10 +268,12 @@ The following plugins are no longer maintained by their developers.
 [candlewaster]: https://notabug.org/candlewaster
 [cedricziel]: https://github.com/cedricziel
 [cef]: https://github.com/cef
+[cheif]: https://github.com/cheif
 [cjblomqvist]: https://github.com/cjblomqvist
 [crisward]: https://github.com/crisward
 [cu12]: https://github.com/cu12
 [darkpixel]: https://github.com/darkpixel
+[deanmarano]: https://github.com/deanmarano
 [dokku]: https://github.com/dokku
 [dokku-community]: https://github.com/dokku-community
 [dyson]: https://github.com/dyson

docs/configuration/domains.md

@@ -13,6 +13,7 @@ domains:enable <app>                           # Enable VHOST support
 domains:remove <app> <domain> [<domain> ...]   # Remove domains from app
 domains:remove-global <domain> [<domain> ...]  # Remove global domain names
 domains:report [<app>|--global] [<flag>]       # Displays a domains report for one or more apps
+domains:reset <app>                            # Reset app domains to global-configured domains
 domains:set <app> <domain> [<domain> ...]      # Set domains for app
 domains:set-global <domain> [<domain> ...]     # Set global domain names
 ```
@@ -33,7 +34,7 @@ If an FQDN such as `dokku.org` is used as the application name, the global virtu
 
 You can optionally override this in a plugin by implementing the `nginx-hostname` plugin trigger. If the `nginx-hostname` plugin has no output, the normal hostname algorithm will be executed. See the [plugin trigger documentation](/docs/development/plugin-triggers.md#nginx-hostname) for more information.
 
-## Disabling VHOSTS
+## Enabling and disabling VHOSTS
 
 If desired, it is possible to disable vhosts with the domains plugin.
 
@@ -41,7 +42,20 @@ If desired, it is possible to disable vhosts with the domains plugin.
 dokku domains:disable node-js-app
 ```
 
-On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. You may change this port by setting `DOKKU_PROXY_PORT` and/or `DOKKU_PROXY_SSL_PORT` (for services configured to use SSL.)
+Vhosts can also be disabled for all apps:
+
+```shell
+dokku domains:disable --all
+```
+
+On subsequent deploys, the nginx virtualhost will be discarded. This is useful when deploying internal-facing services that should not be publicly routeable. As of 0.4.0, nginx will still be configured to proxy your app on some random high port. This allows internal services to maintain the same port between deployments. The non-SSL and SSL ports used can be customized via `dokku proxy:set <app> proxy-port <value>` and `dokku proxy:set <app> proxy-ssl-port <value>` - see the [proxy management documentation](/docs/networking/proxy-management.md#setting-proxy-ports) for details.
+
+To re-enable, run the `domains:enable` subcommand:
+
+```shell
+dokku domains:enable node-js-app
+dokku domains:enable --all
+```
 
 The domains plugin allows you to specify custom domains for applications. This plugin is aware of any ssl certificates that are imported via `certs:add`. Be aware that disabling domains (with `domains:disable`) will override any custom domains.
 
@@ -62,6 +76,9 @@ dokku domains:remove node-js-app dokku.me
 
 # set all custom domains for app
 dokku domains:set node-js-app dokku.me dokku.org
+
+# delete all app domains and configure available global domains on it
+dokku domains:reset node-js-app
 ```
 
 ## Displaying domains reports for an app

docs/configuration/environment-variables.md

@@ -8,7 +8,7 @@ The `config` plugin provides the following commands to manage your variables:
 config:show (<app>|--global)                                                          Pretty-print an app or global environment
 config:bundle (<app>|--global) [--merged]                                             Bundle environment into tarfile
 config:clear (<app>|--global)                                                         Clears environment variables
-config:export (<app>|--global) [--envfile]                                            Export a global or app environment
+config:export (<app>|--global) [--format <format>]                                    Export a global or app environment
 config:get (<app>|--global) KEY                                                       Display a global or app-specific config value
 config:keys (<app>|--global) [--merged]                                               Show keys set in environment
 config:set [--encoded] [--no-restart] (<app>|--global) KEY1=VALUE1 [KEY2=VALUE2 ...]  Set one or more config vars
@@ -22,12 +22,12 @@ Environment variables are available both at run time and during the application
 For buildpack deploys, Dokku will create a  `/app/.env` file that can be used for legacy buildpacks. Note that this is _not_ updated when `config:set` or `config:unset` is called, and is only written during a `deploy` or `ps:rebuild`. Developers are encouraged to instead read from the application environment directly, as the proper values will be available then.
 
 > [!NOTE]
-> Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications.
+> Global environment variables are sourced before app-specific environment variables. This means that app-specific variables will take precedence over global variables. Configuring global environment variables should be considered potentially dangerous as configuration applies to all applications.
 
 You can set multiple environment variables at once:
 
 ```shell
-dokku config:set node-js-app ENV=prod COMPILE_ASSETS=1
+dokku config:set node-js-app APP_ENV=prod COMPILE_ASSETS=1
 ```
 
 Whitespace and special characters get tricky. If you are using dokku locally you don't need to do any special escaping. If you are using dokku over ssh you will need to backslash-escape spaces:
@@ -42,10 +42,23 @@ Dokku can also read base64 encoded values. That's the easiest way to set a value
 dokku config:set --encoded node-js-app KEY="$(base64 -w 0 ~/.ssh/id_rsa)"
 ```
 
+Decoded values are stored byte-for-byte exactly as they were encoded. Be aware that `echo "value" | base64` appends a trailing `\n` before encoding because `echo` always adds a newline, and that newline becomes part of the stored value. This is rarely what you want for short inline values - use `printf '%s'` or `echo -n` instead:
+
+```shell
+dokku config:set --encoded node-js-app KEY="$(printf '%s' "myvalue" | base64 -w 0)"
+dokku config:set --encoded node-js-app KEY="$(echo -n "myvalue" | base64 -w 0)"
+```
+
+For multi-line values from a file (such as an SSH private key), `cat` and `base64 -w 0` preserve the file contents exactly:
+
+```shell
+dokku config:set --encoded node-js-app KEY="$(cat ~/.ssh/id_rsa | base64 -w 0)"
+```
+
 When setting or unsetting environment variables, you may wish to avoid an application restart. This is useful when developing plugins or when setting multiple environment variables in a scripted manner. To do so, use the `--no-restart` flag:
 
 ```shell
-dokku config:set --no-restart node-js-app ENV=prod
+dokku config:set --no-restart node-js-app APP_ENV=prod
 ```
 
 If you wish to have the variables output in an `eval`-compatible form, you can use the `config:export` command
@@ -54,7 +67,7 @@ If you wish to have the variables output in an `eval`-compatible form, you can u
 dokku config:export node-js-app
 # outputs variables in the form:
 #
-#   export ENV='prod'
+#   export APP_ENV='prod'
 #   export COMPILE_ASSETS='1'
 
 # source in all the node-js-app app environment variables
@@ -68,9 +81,38 @@ dokku config:export --format shell node-js-app
 
 # outputs variables in the form:
 #
-#   ENV='prod' COMPILE_ASSETS='1'
+#   APP_ENV='prod' COMPILE_ASSETS='1'
 ```
 
+## Setting Environment Variables via app.json
+
+Environment variables can also be declared in an `app.json` file in your repository root. This is useful for setting default values, generating secrets, or requiring certain variables to be set before deployment.
+
+```json
+{
+  "env": {
+    "SIMPLE_VAR": "default_value",
+    "SECRET_KEY": {
+      "description": "A secret key for signing tokens",
+      "generator": "secret"
+    },
+    "DATABASE_URL": {
+      "description": "PostgreSQL connection string",
+      "required": true
+    }
+  }
+}
+```
+
+Environment variables from `app.json` are processed during the first deploy, before the predeploy script runs. Variables can be configured as:
+
+- **Simple string values**: Set as defaults if not already configured
+- **Generated secrets**: Use `"generator": "secret"` to auto-generate a 64-character hex string
+- **Required variables**: Use `"required": true` to prompt for or require a value
+- **Synced variables**: Use `"sync": true` to update the value on every deploy
+
+For full details on the `env` schema and behavior, see the [app.json documentation](/docs/appendices/file-formats/app-json.md#env).
+
 ## Special Config Variables
 
 The following config variables have special meanings and can be set in a variety of ways. Unless specified via global app config, the values may not be passed into applications. Usage of these values within applications should be considered unsafe, as they are an internal configuration values that may be moved to the internal properties system in the future.
@@ -98,30 +140,15 @@ The following config variables have special meanings and can be set in a variety
 | `DOKKU_QUIET_OUTPUT`           | none                            | `--quiet` flag                                                                                                                                   | Silences certain header output for `dokku` commands. |
 | `DOKKU_RM_CONTAINER`           | none                            | `dokku config:set` <br />                                                                                                                        | Deprecated: Whether to keep `dokku run` containers around or not. |
 | `DOKKU_TRACE`                  | none                            | `dokku trace:on`   <br /> `dokku trace:off` <br /> `--trace` flag                                                                                | Turn on very verbose debugging. |
-| `DOKKU_APP_PROXY_TYPE`         | `nginx`                         | `dokku proxy:set`                                                                                                                                | |
-| `DOKKU_APP_RESTORE`            | `1`                             | `dokku config:set` <br /> `dokku ps:stop`                                                                                                        | |
-| `DOKKU_APP_SHELL`              | `/bin/bash`                     | `dokku config:set`                                                                                                                               | Allows users to change the default shell used by Dokku for `dokku enter` and execution of deployment tasks. |
-| `DOKKU_APP_TYPE`               | `herokuish`                     |  Auto-detected by using buildpacks or dockerfile                                                                                                 | |
-| `DOKKU_CHECKS_DISABLED`        | none                            | `dokku checks:disable`                                                                                                                           | |
-| `DOKKU_CHECKS_ENABLED`         | none                            | `dokku checks:enable`                                                                                                                            | |
-| `DOKKU_CHECKS_SKIPPED`         | none                            | `dokku checks:skip`                                                                                                                              | |
-| `DOKKU_CHECKS_WAIT`            | `5`                             | `dokku config:set`                                                                                                                               | Wait this many seconds for the container to start before running checks.
-| `DOKKU_CHECKS_TIMEOUT`         | `30`                            | `dokku config:set`                                                                                                                               | Wait this many seconds for each response before marking it as a failure.
-| `DOKKU_CHECKS_ATTEMPTS`        | `5`                             | `dokku config:set`                                                                                                                               | Number of retries for to run for a specific check before marking it as a failure
-| `DOKKU_DEFAULT_CHECKS_WAIT`    | `10`                            | `dokku config:set`                                                                                                                               | If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running. |
-| `DOKKU_DISABLE_PROXY`          | none                            | `dokku proxy:disable` <br /> `dokku proxy:enable`                                                                                                | Disables the proxy in front of your application, resulting in publicly routing the docker container. |
-| `DOKKU_DISABLE_ANSI_PREFIX_REMOVAL` | none                       | `dokku config:set` <br /> `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*`                                                 | Disables removal of the ANSI prefix during deploys. Can be used in cases where the client deployer does not understand ansi escape  codes. |
-| `DOKKU_DISABLE_APP_AUTOCREATION` | none                            | `dokku config:set`                                                                                                                               | Disables automatic creation of a non-existent app on deploy. |
-| `DOKKU_DOCKER_STOP_TIMEOUT`    | `10`                            | `dokku config:set`                                                                                                                               | Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands _also_ respect this value. If not specified, the docker defaults for the [docker stop command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.|
-| `DOKKU_DOCKERFILE_CACHE_BUILD` | none                            | `dokku config:set`                                                                                                                               | |
-| `DOKKU_DOCKERFILE_START_CMD`   | none                            | `dokku config:set`                                                                                                                               | |
-| `DOKKU_PARALLEL_ARGUMENTS`.    | none                            | `dokku config:set`                                                                                                                               | Allows passing custom arguments to parallel for `ps:*all` commands |
-| `DOKKU_PROXY_PORT`             | automatically assigned          | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` <br /> `dokku config:set`                                                 | |
-| `DOKKU_PROXY_SSL_PORT`         | automatically assigned          | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` <br /> `dokku config:set`                                                 | |
-| `DOKKU_SKIP_ALL_CHECKS`        | none                            | `dokku config:set`                                                                                                                               | |
-| `DOKKU_SKIP_CLEANUP`           |                                 | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*`                                                                           | When a deploy is triggered, if this is set to a non-empty value, then old docker containers and images will not be removed. |
-| `DOKKU_SKIP_DEFAULT_CHECKS`    |                                 | `dokku config:set`                                                                                                                               | |
-| `DOKKU_SKIP_DEPLOY`            |                                 | `dokku config:set`                                                                                                                               | |
-| `DOKKU_START_CMD`              | none                            | `dokku config:set`                                                                                                                               | Command to run instead of `/start $PROC_TYPE` |
 | `DOKKU_SYSTEM_GROUP`           | `dokku`                         | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*`                                                                           | System group to chown files as. |
 | `DOKKU_SYSTEM_USER`            | `dokku`                         | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*`                                                                           | System user to chown files as. |
+
+## Properties
+
+### Internal properties
+
+The following property is recorded internally by the config plugin and is not exposed via `config:report`:
+
+| Property | Description | Source |
+|---|---|---|
+| `env-migrated` | Migration sentinel that records that the per-app or global `ENV` file has been drained out of its pre-0.38.0 location into the config path. The drain happens once: a file found at the old path once this is recorded is never imported, since the config path holds every change made since. Such a file is removed when it agrees with the current config, and otherwise moved aside to `ENV.migrated` with the keys it disagrees on named in a warning. The preserved copy is left for review and should be deleted afterwards, since it holds keys that were unset on purpose | `plugins/config/migrate.go` writes `"true"` once the file has been drained |

docs/configuration/ssl.md

@@ -41,6 +41,9 @@ dokku certs:add node-js-app < cert-key.tar
 cat yourdomain_com.crt yourdomain_com.ca-bundle > server.crt
 ```
 
+> [!NOTE]
+> Archives passed to `certs:add` are validated before extraction to prevent path traversal and symlink escape attacks. Archives containing absolute paths, parent directory traversal entries, or symlinks pointing outside the extraction directory will be rejected.
+
 #### SSL and Multiple Domains
 
 When an SSL certificate is associated to an application, the certificate will be associated with _all_ domains currently associated with said application. Your certificate _should_ be associated with all of those domains, otherwise accessing the application will result in SSL errors. If you wish to remove one of the domains from the application, refer to the [domain configuration documentation](/docs/configuration/domains.md).
@@ -140,8 +143,27 @@ Certain versions of nginx have bugs that prevent [HTTP/2](https://nginx.org/en/d
 
 When your app is served from port `80` then the `/home/dokku/APP/nginx.conf` file will automatically be updated to instruct nginx to respond to ssl on port 443 as a new cert is added. If your app uses a non-standard port (perhaps you have a dockerfile deploy exposing port `99999`) you may need to manually expose an ssl port via `dokku ports:add <APP> https:443:99999`.
 
+If an `https:443:*` port mapping already exists when a certificate is installed or renewed, Dokku will preserve it rather than rewriting it from the `http:80:*` mappings. This allows apps that terminate TLS inside the container (for example, with a configuration like `http:80:80 https:443:443`) to keep their explicit mapping across `dokku certs:add` and unattended renewals.
+
 ## Other
 
 ### Running behind a proxy (`X-Forwarded-Ssl`, etc.)
 
 See the [running behind another proxy documentation](/docs/networking/proxies/nginx.md#running-behind-another-proxy--configuring-x-forwarded--headers) for more information on how to configure your Nginx config when your server is running behind a proxy (e.g. load balancer, etc.).
+
+## Properties
+
+### Read-only flags
+
+The following flags surface in `certs:report` but are not managed by `certs:set` - they are derived from the on-disk certificate:
+
+| Flag | Description |
+|---|---|
+| `--ssl-enabled` | `true` when an SSL certificate is installed for the app |
+| `--ssl-dir` | Absolute path to the per-app certificate directory |
+| `--ssl-hostnames` | Hostnames the certificate covers (CN plus Subject Alternative Names) |
+| `--ssl-issuer` | Certificate issuer DN |
+| `--ssl-subject` | Certificate subject DN |
+| `--ssl-verified` | `true` if the certificate chain verifies against the system CA bundle |
+| `--ssl-expires-at` | Certificate `notAfter` timestamp |
+| `--ssl-starts-at` | Certificate `notBefore` timestamp |

docs/deployment/application-deployment.md

@@ -143,11 +143,11 @@ dokku letsencrypt:cron-job --add
 
 ### Skipping deployment
 
-If you only want to rebuild and tag a container, you can skip the deployment phase by setting `$DOKKU_SKIP_DEPLOY` to `true` by running:
+If you only want to rebuild and tag a container, you can skip the deployment phase by setting the `skip-deploy` property to `true`:
 
 ``` shell
 # on the Dokku host
-dokku config:set ruby-getting-started DOKKU_SKIP_DEPLOY=true
+dokku ps:set ruby-getting-started skip-deploy true
 ```
 
 ### Redeploying or restarting

docs/deployment/application-management.md

@@ -8,11 +8,12 @@ apps:clone <old-app> <new-app>                 # Clones an app
 apps:create <app>                              # Create a new app
 apps:destroy <app>                             # Permanently destroy an app
 apps:exists <app>                              # Checks if an app exists
-apps:list                                      # List your apps
+apps:list [--format stdout|json]               # List your apps
 apps:lock <app>                                # Locks an app for deployment
 apps:locked <app>                              # Checks if an app is locked for deployment
 apps:rename <old-app> <new-app>                # Rename an app
 apps:report [<app>] [<flag>]                   # Display report about an app
+apps:set [--global] <app> <key> (<value>)      # Set or clear an apps property for an app
 apps:unlock <app>                              # Unlocks an app for deployment
 ```
 
@@ -46,6 +47,18 @@ node-js-app
 python-app
 ```
 
+You can also retrieve the list of apps as a JSON array by using the `--format json` flag, which is useful for programmatic consumption:
+
+```shell
+dokku apps:list --format json
+```
+
+```json
+["node-js-app","python-app"]
+```
+
+When no apps exist, the JSON output is an empty array (`[]`).
+
 ### Checking if an application exists
 
 For CI/CD pipelines, it may be useful to see if an application exists before creating a "review" application for a specific branch. You can do so via the `apps:exists` command:
@@ -78,6 +91,20 @@ Once created, you can configure the application as normal, and deploy the applic
 - Create and link datastores.
 - Set environment variables.
 
+### Disabling automatic app creation
+
+By default, pushing to a git remote for an app that does not yet exist on the Dokku host will cause the app to be created automatically. On shared or production hosts this may be undesirable - operators may prefer that an explicit `apps:create` is required first. The `disable-autocreation` global property controls this behavior:
+
+```shell
+dokku apps:set --global disable-autocreation true
+```
+
+While set, pushes targeting an app that does not exist will be rejected. The default behavior may be restored by passing an empty value:
+
+```shell
+dokku apps:set --global disable-autocreation
+```
+
 ### Removing a deployed app
 
 In some cases, you may need to destroy an application, whether it is because the application is temporary or because it was misconfigured. In these cases, you can use the `apps:destroy` command. Performing any destructive actions in Dokku requires confirmation, and this command will ask for the name of the application being deleted before doing so.
@@ -297,3 +324,26 @@ You can pass flags which will output only the value of the specific information
 ```shell
 dokku apps:report node-js-app --app-dir
 ```
+
+## Properties
+
+### Settable properties
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `apps:report`. The JSON keys emitted by `apps:report --format json` are the same names with the leading `--app-` stripped (e.g. `global-disable-autocreation`). Legacy keys with the `app-` prefix (e.g. `app-global-disable-autocreation`) 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 |
+|---|---|---|---|---|
+| `disable-autocreation` | global only | `false` | `--app-global-disable-autocreation` | When `true`, pushes to a remote for an app that does not yet exist are rejected instead of auto-creating the app |
+
+### Read-only flags
+
+The following flags surface in `apps:report` but are not managed by `apps:set`:
+
+| Flag | Description |
+|---|---|
+| `--app-created-at` | UNIX timestamp of app creation |
+| `--app-deploy-source` | Source kind of the last deploy (`git`, `archive`, `docker-image`, `git-sync`) |
+| `--app-deploy-source-metadata` | Free-form metadata for the deploy source (commit sha, image ref, URL) |
+| `--app-dir` | Absolute path of the app root on disk |
+| `--app-locked` | `true` while a deploy or rebuild holds the app lock |

docs/deployment/builders/builder-management.md

@@ -82,6 +82,28 @@ The default value may be set by passing an empty value for the option.
 dokku builder:set --global build-dir
 ```
 
+#### Skipping container and image cleanup
+
+After a successful deploy, Dokku removes old containers and images that are no longer referenced by the app. On hosts where image rebuilds are expensive or where operators want to retain prior images for manual rollback, this cleanup can be disabled per-app or globally via the `skip-cleanup` property:
+
+```shell
+dokku builder:set node-js-app skip-cleanup true
+```
+
+The property can also be set globally:
+
+```shell
+dokku builder:set --global skip-cleanup true
+```
+
+The default behavior (cleanup enabled) may be restored by passing an empty value:
+
+```shell
+dokku builder:set node-js-app skip-cleanup
+```
+
+For backwards compatibility with bootstrap-time configuration, the `DOKKU_SKIP_CLEANUP` environment variable in `/etc/environment` or `~dokku/.dokkurc/*` is still honored when the `skip-cleanup` property is unset. The property is the canonical interface and takes precedence when set.
+
 ### Displaying builder reports for an app
 
 You can get a report about the app's builder status using the `builder:report` command:
@@ -150,3 +172,24 @@ Custom plugins names _must_ have the prefix `builder-` or builder overriding via
 Builders can use any tools available on the system to build the docker image, and may even be used to schedule building off-server. The only current requirement is that the image must exist on the server at the end of the `builder-build` command, though this requirement may be relaxed in a future release.
 
 For a simple example of how to implement this trigger, see `builder-pack`, which utilizes a cli tool - `pack-cli` - to generate an OCI image that is compatible with Docker and can be scheduled by the official scheduling plugins.
+
+## Properties
+
+### Settable properties
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `builder:report`. The JSON keys emitted by `builder:report --format json` are the same names with the leading `--builder-` stripped (e.g. `selected`, `global-selected`, `computed-selected`). Legacy keys with the `builder-` prefix 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 |
+|---|---|---|---|---|
+| `build-dir` | app + global | none | `--builder-build-dir`, `--builder-global-build-dir`, `--builder-computed-build-dir` | Subdirectory within the repository to use as the build context |
+| `selected` | app + global | none | `--builder-selected`, `--builder-global-selected`, `--builder-computed-selected` | Builder plugin to use; overrides automatic detection |
+| `skip-cleanup` | app + global | `false` | `--builder-skip-cleanup`, `--builder-global-skip-cleanup`, `--builder-computed-skip-cleanup` | When `true`, leaves intermediate build artifacts in place after the build |
+
+### Read-only flags
+
+The following flags surface in `builder:report` but are not managed by `builder:set`:
+
+| Flag | Description |
+|---|---|
+| `--builder-detected` | Builder auto-selected for the app when `selected` is unset |

docs/deployment/builders/buildpack-management.md

@@ -0,0 +1,225 @@
+# Buildpacks Management
+
+> [!NOTE]
+> Buildpacks commands apply to both herokuish and CNB-based builds
+
+```
+buildpacks:add [--index 1] <app> <buildpack>            # Add new app buildpack while inserting into list of buildpacks if necessary
+buildpacks:clear <app>                                  # Clear all buildpacks set on the app
+buildpacks:list <app>                                   # List all buildpacks for an app
+buildpacks:remove <app> <buildpack>                     # Remove a buildpack set on the app
+buildpacks:report [<app>] [<flag>]                      # Displays a buildpack report for one or more apps
+buildpacks:set [--index 1] <app> <buildpack>            # Set new app buildpack at a given position defaulting to the first buildpack if no index is specified
+buildpacks:set --replace <app> <buildpack> [<buildpack> ...] # Replace the entire ordered buildpack list with the specified buildpacks
+```
+
+## Usage
+
+### Listing Buildpacks in Use
+
+The `buildpacks:list` command can be used to show buildpacks that have been set for an app. This will omit any auto-detected buildpacks.
+
+```shell
+# running for an app with no buildpacks specified
+dokku buildpacks:list node-js-app
+```
+
+```
+-----> test buildpack urls
+```
+
+```shell
+# running for an app with two buildpacks specified
+dokku buildpacks:list node-js-app
+```
+
+```
+-----> test buildpack urls
+       https://github.com/heroku/heroku-buildpack-python.git
+       https://github.com/heroku/heroku-buildpack-nodejs.git
+```
+
+### Adding custom buildpacks
+
+> Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.
+
+To add a custom buildpack, use the `buildpacks:add` command:
+
+```shell
+dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git
+```
+
+When no buildpacks are currently specified, the specified buildpack will be the only one executed for detection and compilation.
+
+Multiple buildpacks may be specified by using the `buildpacks:add` command multiple times.
+
+```shell
+dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
+dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git
+```
+
+Buildpacks are executed in order, may be inserted at a specified index via the `--index` flag. This flag is specified starting at a 1-index value.
+
+```shell
+# will add the golang buildpack at the second position, bumping all proceeding ones by 1 position
+dokku buildpacks:add --index 2 node-js-app https://github.com/heroku/heroku-buildpack-golang.git
+```
+
+### Overwriting a buildpack position
+
+In some cases, it may be necessary to swap out a given buildpack. Rather than needing to re-specify each buildpack, the `buildpacks:set` command can be used to overwrite a buildpack at a given position.
+
+```shell
+dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
+```
+
+By default, this will overwrite the _first_ buildpack specified. To specify an index, the `--index` flag may be used. This flag is specified starting at a 1-index value, and defaults to `1`.
+
+```shell
+# the following are equivalent commands
+dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
+dokku buildpacks:set --index 1 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
+```
+
+If the index specified is larger than the number of buildpacks currently configured, the buildpack will be appended to the end of the list.
+
+```shell
+dokku buildpacks:set --index 99 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
+```
+
+### Replacing the entire buildpack list
+
+To replace the complete ordered buildpack list in a single command, use the `--replace` flag. This is useful for tooling that needs to apply a full buildpack list atomically instead of running `buildpacks:clear` followed by multiple `buildpacks:add` calls.
+
+```shell
+dokku buildpacks:set --replace node-js-app https://github.com/heroku/heroku-buildpack-ruby.git https://github.com/heroku/heroku-buildpack-nodejs.git
+```
+
+The buildpacks are executed in the order they are specified, and the previous list is discarded. If any specified buildpack is invalid, the existing list is left unchanged.
+
+A single buildpack may also be specified to replace the entire list with just that buildpack:
+
+```shell
+dokku buildpacks:set --replace node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
+```
+
+> [!NOTE]
+> The `--replace` flag cannot be combined with the `--index` flag. To remove all buildpacks, use the `buildpacks:clear` command instead of `--replace` with no buildpacks.
+
+### Removing a buildpack
+
+> At least one of a buildpack or index must be specified
+
+A single buildpack can be removed by name via the `buildpacks:remove` command.
+
+```shell
+dokku buildpacks:remove node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
+```
+
+Buildpacks can also be removed by index via the `--index` flag. This flag is specified starting at a 1-index value.
+
+```shell
+dokku buildpacks:remove node-js-app --index 1
+```
+
+### Clearing all buildpacks
+
+> This does not affect automatically detected buildpacks, nor does it impact any specified `BUILDPACK_URL` environment variable.
+
+The `buildpacks:clear` command can be used to clear all configured buildpacks for a specified app.
+
+```shell
+dokku buildpacks:clear node-js-app
+```
+
+### Using a specific buildpack version
+
+> Always remember to pin your buildpack versions when using the multi-buildpacks method, or you may find deploys changing your deployed environment.
+
+By default, builders will pin their vendored buildpacks, resulting in a consistent build result for your application. There may be occasions where the pinned version results in a broken deploy, or does not have a particular feature that is required to build your project. To use a more recent version of a given buildpack, the buildpack may be specified _without_ a Git commit SHA like so:
+
+```shell
+# using the latest nodejs buildpack
+dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs
+```
+
+This will use the latest commit on the `master` branch of the specified buildpack. To pin to a newer version of a buildpack, a sha may also be specified by using the form `REPOSITORY_URL#COMMIT_SHA`, where `COMMIT_SHA` is any tree-ish git object - usually a git tag.
+
+```shell
+# using v87 of the nodejs buildpack
+dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs#v87
+```
+
+### Specifying buildpacks via app.json
+
+Buildpacks can also be specified in the `app.json` file at the root of your repository:
+
+```json
+{
+  "buildpacks": [
+    {
+      "url": "heroku/python"
+    }
+  ]
+}
+```
+
+Buildpacks configured via `buildpacks:add` or `buildpacks:set` commands take precedence over those specified in `app.json`. If no buildpacks are configured via commands and `app.json` contains a `buildpacks` entry, those buildpacks will be used.
+
+Shorthand buildpack references (e.g., `heroku/python`) are expanded to full GitHub URLs automatically.
+
+### Displaying buildpack reports for an app
+
+You can get a report about the app's buildpacks status using the `buildpacks:report` command:
+
+```shell
+dokku buildpacks:report
+```
+
+```
+=====> node-js-app buildpacks information
+       Buildpacks computed stack:  gliderlabs/herokuish:v0.7.0-22
+       Buildpacks global stack:    gliderlabs/herokuish:latest-24
+       Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git
+       Buildpacks stack:           gliderlabs/herokuish:v0.7.0-20
+=====> python-sample buildpacks information
+       Buildpacks computed stack:  gliderlabs/herokuish:latest-24
+       Buildpacks global stack:    gliderlabs/herokuish:latest-24
+       Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git,https://github.com/heroku/heroku-buildpack-python.git
+       Buildpacks stack:
+=====> ruby-sample buildpacks information
+       Buildpacks computed stack:  gliderlabs/herokuish:latest-24
+       Buildpacks global stack:    gliderlabs/herokuish:latest-24
+       Buildpacks list:
+       Buildpacks stack:
+```
+
+You can run the command for a specific app also.
+
+```shell
+dokku buildpacks:report node-js-app
+```
+
+```
+=====> node-js-app buildpacks information
+       Buildpacks list:               https://github.com/heroku/heroku-buildpack-nodejs.git
+```
+
+You can pass flags which will output only the value of the specific information you want. For example:
+
+```shell
+dokku buildpacks:report node-js-app --buildpacks-list
+```
+
+## Properties
+
+### Settable properties
+
+These properties are managed via `buildpacks:set-property` (the legacy command name for this plugin).
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `buildpacks:report`. The JSON keys emitted by `buildpacks:report --format json` are the same names with the leading `--buildpacks-` stripped (e.g. `stack`, `global-stack`, `computed-stack`). Legacy keys with the `buildpacks-` prefix 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 |
+|---|---|---|---|---|
+| `stack` | app + global | none | `--buildpacks-stack`, `--buildpacks-global-stack`, `--buildpacks-computed-stack` | Herokuish stack image used to compile the app (e.g. `heroku/heroku:24`) |

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

@@ -14,8 +14,8 @@ buildpacks:set-property [--global|<app>] <key> <value>  # Set or clear a buildpa
 
 Cloud Native Buildpacks are an evolution over the Buildpacks technology provided by the Herokuish builder. See the [herokuish buildpacks documentation](/docs/deployment/builders/herokuish-buildpacks.md) for more information on how to clear buildpack build cache for an application.
 
-> [!WARNING]
-> This functionality uses the `pack` cli from the [Cloud Native Buildpacks](https://buildpacks.io) project to build apps. As the integration is experimental in Dokku, it is likely to change over time.
+> [!NOTE]
+> This functionality uses the `pack` cli from the [Cloud Native Buildpacks](https://buildpacks.io) project to build apps.
 
 ## Usage
 
@@ -27,7 +27,7 @@ Builds will proceed with the `pack` cli for the app from then on.
 
 ### Caveats
 
-As this functionality is highly experimental, there are a number of caveats. Please note that not all issues are listed below.
+While pack is well-supported in Dokku, there are a number of caveats. Please note that not all issues are listed below.
 
 - Specifying specific buildpacks is not currently possible.
     - A future release will add support for specifying buildpacks via the `buildpacks` plugin.
@@ -41,16 +41,7 @@ As this functionality is highly experimental, there are a number of caveats. Ple
 
 ### Detection
 
-This builder will be auto-detected in either the following cases:
-
-- The `DOKKU_CNB_EXPERIMENTAL` app environment variable is set to `1`.
-
-    ```shell
-    dokku config:set --no-restart node-js-app DOKKU_CNB_EXPERIMENTAL=1
-    ```
-
-- A `project.toml` file exists in the root of the app repository.
-    - This file is consumed by `pack-cli` and used to describe how the app is built.
+This builder will be auto-detected if a `project.toml` file exists in the root of the app repository.  This file is consumed by `pack-cli` and used to describe how the app is built.
 
 The builder can also be specified via the `builder:set` command:
 
@@ -107,18 +98,20 @@ dokku builder-pack:report
 ```
 =====> node-js-app builder-pack information
        Builder pack computed projecttoml path: project2.toml
-       Builder pack global projecttoml path:   project.toml
+       Builder pack global projecttoml path:
        Builder pack projecttoml path:          project2.toml
 =====> python-sample builder-pack information
        Builder pack computed projecttoml path: project.toml
-       Builder pack global projecttoml path:   project.toml
+       Builder pack global projecttoml path:
        Builder pack projecttoml path:
 =====> ruby-sample builder-pack information
        Builder pack computed projecttoml path: project.toml
-       Builder pack global projecttoml path:   project.json
+       Builder pack global projecttoml path:
        Builder pack projecttoml path:
 ```
 
+The `projecttoml-path` and `global-projecttoml-path` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-projecttoml-path` key holds the effective value used at build time, falling back to the global value (where one has been set) and then to the built-in default of `project.toml`.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -128,7 +121,7 @@ dokku builder-pack:report node-js-app
 ```
 =====> node-js-app builder-pack information
        Builder pack computed projecttoml path: project2.toml
-       Builder pack global projecttoml path:   project.toml
+       Builder pack global projecttoml path:
        Builder pack projecttoml path:          project2.toml
 ```
 
@@ -174,3 +167,11 @@ dokku buildpacks:set-property --global stack
 ### Specifying commands via Procfile
 
 See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app.
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `projecttoml-path` | app + global | `project.toml` | `--builder-pack-projecttoml-path`, `--builder-pack-global-projecttoml-path`, `--builder-pack-computed-projecttoml-path` | Path within the app to the CNB `project.toml` manifest, relative to the build root |

docs/deployment/builders/dockerfiles.md

@@ -82,18 +82,20 @@ dokku builder-dockerfile:report
 ```
 =====> node-js-app builder-dockerfile information
        Builder dockerfile computed dockerfile path: Dockerfile2
-       Builder dockerfile global dockerfile path:   Dockerfile
+       Builder dockerfile global dockerfile path:
        Builder dockerfile dockerfile path:          Dockerfile2
 =====> python-sample builder-dockerfile information
        Builder dockerfile computed dockerfile path: Dockerfile
-       Builder dockerfile global dockerfile path:   Dockerfile
+       Builder dockerfile global dockerfile path:
        Builder dockerfile dockerfile path:
 =====> ruby-sample builder-dockerfile information
        Builder dockerfile computed dockerfile path: Dockerfile
-       Builder dockerfile global dockerfile path:   Dockerfile
+       Builder dockerfile global dockerfile path:
        Builder dockerfile dockerfile path:
 ```
 
+The `dockerfile-path` and `global-dockerfile-path` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-dockerfile-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 `Dockerfile`.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -103,7 +105,7 @@ dokku builder-dockerfile:report node-js-app
 ```
 =====> node-js-app builder-dockerfile information
        Builder dockerfile computed dockerfile path: Dockerfile2
-       Builder dockerfile global dockerfile path:   Dockerfile
+       Builder dockerfile global dockerfile path:
        Builder dockerfile dockerfile path:          Dockerfile2
 ```
 
@@ -185,7 +187,7 @@ You would adjust the cache directory for whatever application cache you have, e.
 
 ### Customizing the run command
 
-By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker ability of overriding the `CMD` or passing parameters to your `ENTRYPOINT` setting `$DOKKU_DOCKERFILE_START_CMD`. Let's say for example you are deploying a base Node.js image, with the following `ENTRYPOINT`:
+By default no arguments are passed to `docker run` when deploying the container and the `CMD` or `ENTRYPOINT` defined in the `Dockerfile` are executed. You can take advantage of docker's ability to override the `CMD` or pass parameters to your `ENTRYPOINT` by setting the `dockerfile-start-cmd` property on the `ps` plugin. Let's say for example you are deploying a base Node.js image, with the following `ENTRYPOINT`:
 
 ```Dockerfile
 ENTRYPOINT ["node"]
@@ -194,12 +196,14 @@ ENTRYPOINT ["node"]
 You can do:
 
 ```shell
-dokku config:set node-js-app DOKKU_DOCKERFILE_START_CMD="--harmony server.js"
+dokku ps:set node-js-app dockerfile-start-cmd "--harmony server.js"
 ```
 
-To tell Docker what to run.
+To tell Docker what to run. Pass an empty value to clear the override:
 
-Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disable Docker's image layer cache. Lastly, for more granular build control, you may also pass any `docker build` option to `docker`, by setting `$DOKKU_DOCKER_BUILD_OPTS`.
+```shell
+dokku ps:set node-js-app dockerfile-start-cmd
+```
 
 ### Procfiles and multiple processes
 
@@ -211,3 +215,11 @@ See the [Procfile documentation](/docs/processes/process-management.md#procfile)
 ### Exposed ports
 
 See the [port management documentation](/docs/networking/port-management.md) for more information on how Dokku exposes ports for applications and how you can configure these for your app.
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `dockerfile-path` | app + global | `Dockerfile` | `--builder-dockerfile-dockerfile-path`, `--builder-dockerfile-global-dockerfile-path`, `--builder-dockerfile-computed-dockerfile-path` | Path within the app to the Dockerfile used by the dockerfile builder |

docs/deployment/builders/herokuish-buildpacks.md

@@ -4,12 +4,6 @@
 > Subcommands new as of 0.15.0
 
 ```
-buildpacks:add [--index 1] <app> <buildpack>            # Add new app buildpack while inserting into list of buildpacks if necessary
-buildpacks:clear <app>                                  # Clear all buildpacks set on the app
-buildpacks:list <app>                                   # List all buildpacks for an app
-buildpacks:remove <app> <buildpack>                     # Remove a buildpack set on the app
-buildpacks:report [<app>] [<flag>]                      # Displays a buildpack report for one or more apps
-buildpacks:set [--index 1] <app> <buildpack>            # Set new app buildpack at a given position defaulting to the first buildpack if no index is specified
 buildpacks:set-property [--global|<app>] <key> <value>  # Set or clear a buildpacks property for an app
 ```
 
@@ -49,104 +43,6 @@ dokku builder:set node-js-app selected herokuish
 
 > Dokku will only select the `dockerfile` builder if both the `herokuish` and `pack` builders are not detected and a Dockerfile exists. See the [dockerfile builder documentation](/docs/deployment/builders/dockerfiles.md) for more information on how that builder functions.
 
-### Listing Buildpacks in Use
-
-The `buildpacks:list` command can be used to show buildpacks that have been set for an app. This will omit any auto-detected buildpacks.
-
-```shell
-# running for an app with no buildpacks specified
-dokku buildpacks:list node-js-app
-```
-
-```
------> test buildpack urls
-```
-
-```shell
-# running for an app with two buildpacks specified
-dokku buildpacks:list node-js-app
-```
-
-```
------> test buildpack urls
-       https://github.com/heroku/heroku-buildpack-python.git
-       https://github.com/heroku/heroku-buildpack-nodejs.git
-```
-
-### Adding custom buildpacks
-
-> Please check the documentation for your particular buildpack as you may need to include configuration files (such as a Procfile) in your project root.
-
-To add a custom buildpack, use the `buildpacks:add` command:
-
-```shell
-dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git
-```
-
-When no buildpacks are currently specified, the specified buildpack will be the only one executed for detection and compilation.
-
-Multiple buildpacks may be specified by using the `buildpacks:add` command multiple times.
-
-```shell
-dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
-dokku buildpacks:add node-js-app https://github.com/heroku/heroku-buildpack-nodejs.git
-```
-
-Buildpacks are executed in order, may be inserted at a specified index via the `--index` flag. This flag is specified starting at a 1-index value.
-
-```shell
-# will add the golang buildpack at the second position, bumping all proceeding ones by 1 position
-dokku buildpacks:add --index 2 node-js-app https://github.com/heroku/heroku-buildpack-golang.git
-```
-
-### Overwriting a buildpack position
-
-In some cases, it may be necessary to swap out a given buildpack. Rather than needing to re-specify each buildpack, the `buildpacks:set` command can be used to overwrite a buildpack at a given position.
-
-```shell
-dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
-```
-
-By default, this will overwrite the _first_ buildpack specified. To specify an index, the `--index` flag may be used. This flag is specified starting at a 1-index value, and defaults to `1`.
-
-```shell
-# the following are equivalent commands
-dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
-dokku buildpacks:set --index 1 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
-```
-
-If the index specified is larger than the number of buildpacks currently configured, the buildpack will be appended to the end of the list.
-
-```shell
-dokku buildpacks:set --index 99 node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
-```
-
-### Removing a buildpack
-
-> At least one of a buildpack or index must be specified
-
-A single buildpack can be removed by name via the `buildpacks:remove` command.
-
-```shell
-dokku buildpacks:remove node-js-app https://github.com/heroku/heroku-buildpack-ruby.git
-```
-
-Buildpacks can also be removed by index via the `--index` flag. This flag is specified starting at a 1-index value.
-
-```shell
-dokku buildpacks:remove node-js-app --index 1
-```
-
-### Clearing all buildpacks
-
-> This does not affect automatically detected buildpacks, nor does it impact any specified `BUILDPACK_URL` environment variable.
-
-The `buildpacks:clear` command can be used to clear all configured buildpacks for a specified app.
-
-```shell
-dokku buildpacks:clear node-js-app
-```
-
 ### Customizing the Buildpack stack builder
 
 > [!IMPORTANT]
@@ -207,49 +103,6 @@ The default value may be set by passing an empty value for the option.
 dokku builder-herokuish:set --global allowed
 ```
 
-### Displaying buildpack reports for an app
-
-You can get a report about the app's buildpacks status using the `buildpacks:report` command:
-
-```shell
-dokku buildpacks:report
-```
-
-```
-=====> node-js-app buildpacks information
-       Buildpacks computed stack:  gliderlabs/herokuish:v0.7.0-22
-       Buildpacks global stack:    gliderlabs/herokuish:latest-24
-       Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git
-       Buildpacks stack:           gliderlabs/herokuish:v0.7.0-20
-=====> python-sample buildpacks information
-       Buildpacks computed stack:  gliderlabs/herokuish:latest-24
-       Buildpacks global stack:    gliderlabs/herokuish:latest-24
-       Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git,https://github.com/heroku/heroku-buildpack-python.git
-       Buildpacks stack:
-=====> ruby-sample buildpacks information
-       Buildpacks computed stack:  gliderlabs/herokuish:latest-24
-       Buildpacks global stack:    gliderlabs/herokuish:latest-24
-       Buildpacks list:
-       Buildpacks stack:
-```
-
-You can run the command for a specific app also.
-
-```shell
-dokku buildpacks:report node-js-app
-```
-
-```
-=====> node-js-app buildpacks information
-       Buildpacks list:               https://github.com/heroku/heroku-buildpack-nodejs.git
-```
-
-You can pass flags which will output only the value of the specific information you want. For example:
-
-```shell
-dokku buildpacks:report node-js-app --buildpacks-list
-```
-
 ### Displaying builder-herokuish reports for an app
 
 > [!IMPORTANT]
@@ -264,18 +117,20 @@ dokku builder-herokuish:report
 ```
 =====> node-js-app builder-herokuish information
        Builder herokuish computed allowed: false
-       Builder herokuish global allowed:   true
+       Builder herokuish global allowed:
        Builder herokuish allowed:          false
 =====> python-sample builder-herokuish information
        Builder herokuish computed allowed: true
-       Builder herokuish global allowed:   true
+       Builder herokuish global allowed:
        Builder herokuish allowed:
 =====> ruby-sample builder-herokuish information
        Builder herokuish computed allowed: true
-       Builder herokuish global allowed:   true
+       Builder herokuish global allowed:
        Builder herokuish allowed:
 ```
 
+The `allowed` and `global-allowed` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-allowed` key holds the effective value used at build time, falling back to the global value (where one has been set) and then to the built-in default (`true` on amd64, `false` otherwise).
+
 You can run the command for a specific app also.
 
 ```shell
@@ -285,7 +140,7 @@ dokku builder-herokuish:report node-js-app
 ```
 =====> node-js-app builder-herokuish information
        Builder herokuish computed allowed: false
-       Builder herokuish global allowed:   true
+       Builder herokuish global allowed:
        Builder herokuish allowed:          false
 ```
 
@@ -309,24 +164,6 @@ If an application was previously deployed via Dockerfile, the following commands
 dokku ports:clear node-js-app
 ```
 
-### Using a specific buildpack version
-
-> Always remember to pin your buildpack versions when using the multi-buildpacks method, or you may find deploys changing your deployed environment.
-
-By default, Dokku uses the [gliderlabs/herokuish](https://github.com/gliderlabs/herokuish/) project, which pins all of it's vendored buildpacks. There may be occasions where the pinned version results in a broken deploy, or does not have a particular feature that is required to build your project. To use a more recent version of a given buildpack, the buildpack may be specified _without_ a Git commit SHA like so:
-
-```shell
-# using the latest nodejs buildpack
-dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs
-```
-
-This will use the latest commit on the `master` branch of the specified buildpack. To pin to a newer version of a buildpack, a sha may also be specified by using the form `REPOSITORY_URL#COMMIT_SHA`, where `COMMIT_SHA` is any tree-ish git object - usually a git tag.
-
-```shell
-# using v87 of the nodejs buildpack
-dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs#v87
-```
-
 ### `curl` build timeouts
 
 Certain buildpacks may time out in retrieving dependencies via `curl`. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to `gzip: stdin: unexpected end of file` after a `curl` command.
@@ -345,3 +182,40 @@ See the [repository management documentation](/docs/advanced-usage/repository-ma
 ### Specifying commands via Procfile
 
 See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app.
+
+### Listing Buildpacks in Use
+
+See the [buildpack management documentation](/docs/deployment/builders/buildpack-management.md#listing-buildpacks-in-use) for more information on how to list buildpacks in use.
+
+### Adding custom buildpacks
+
+See the [buildpack management documentation](/docs/deployment/builders/buildpack-management.md#adding-custom-buildpacks) for more information on how to add custom buildpacks.
+
+### Overwriting a buildpack position
+
+See the [buildpack management documentation](/docs/deployment/builders/buildpack-management.md#overwriting-a-buildpack-position) for more information on how to overwrite a buildpack position.
+
+### Removing a buildpack
+
+See the [buildpack management documentation](/docs/deployment/builders/buildpack-management.md#removing-a-buildpack) for more information on how to remove a buildpack.
+
+### Clearing all buildpacks
+
+See the [buildpack management documentation](/docs/deployment/builders/buildpack-management.md#clearing-all-buildpacks) for more information on how to clear all buildpacks.
+
+### Using a specific buildpack version
+
+See the [buildpack management documentation](/docs/deployment/builders/buildpack-management.md#using-a-specific-buildpack-version) for more information on how to using a specific buildpack version
+
+
+### Displaying buildpack reports for an app
+
+See the [buildpack management documentation](/docs/deployment/builders/buildpack-management.md#displaying-buildpack-reports-for-an-app) for more information on how to display buildpack reports for an app.
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `allowed` | app + global | `true` | `--builder-herokuish-allowed`, `--builder-herokuish-global-allowed`, `--builder-herokuish-computed-allowed` | When `false`, the herokuish builder is skipped during builder detection for this app |

docs/deployment/builders/lambda.md

@@ -84,18 +84,20 @@ dokku builder-lambda:report
 ```
 =====> node-js-app builder-lambda information
        Builder lambda computed lambdayml path: lambda2.yml
-       Builder lambda global lambdayml path:   lambda.yml
+       Builder lambda global lambdayml path:
        Builder lambda lambdayml path:          lambda2.yml
 =====> python-sample builder-lambda information
        Builder lambda computed lambdayml path: lambda.yml
-       Builder lambda global lambdayml path:   lambda.yml
+       Builder lambda global lambdayml path:
        Builder lambda lambdayml path:
 =====> ruby-sample builder-lambda information
        Builder lambda computed lambdayml path: lambda.yml
-       Builder lambda global lambdayml path:   lambda.yml
+       Builder lambda global lambdayml path:
        Builder lambda lambdayml path:
 ```
 
+The `lambdayml-path` and `global-lambdayml-path` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-lambdayml-path` key holds the effective value used at build time, falling back to the global value (where one has been set) and then to the built-in default of `lambda.yml`.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -105,7 +107,7 @@ dokku builder-lambda:report node-js-app
 ```
 =====> node-js-app builder-lambda information
        Builder lambda computed lambdayml path: lambda2.yml
-       Builder lambda global lambdayml path:   lambda.yml
+       Builder lambda global lambdayml path:
        Builder lambda lambdayml path:          lambda2.yml
 ```
 
@@ -118,3 +120,11 @@ dokku builder-lambda:report node-js-app --builder-lambda-lambdayml-path
 ```
 lambda2.yml
 ```
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `lambdayml-path` | app + global | `lambda.yml` | `--builder-lambda-lambdayml-path`, `--builder-lambda-global-lambdayml-path`, `--builder-lambda-computed-lambdayml-path` | Path within the app to the `lambda.yml` manifest used by the lambda builder |

docs/deployment/builders/nixpacks.md

@@ -80,28 +80,10 @@ dokku builder-nixpacks:set --global nixpackstoml-path
 
 ### Disabling cache
 
-Cache is enabled by default, but can be disabled by setting the `no-cache` property to `true`:
+Disable cache using the [docker-options] plugin:
 
 ```shell
-dokku builder-nixpacks:set node-js-app no-cache true
-```
-
-The default value may be set by passing an empty value for the option:
-
-```shell
-dokku builder-nixpacks:set node-js-app no-cache
-```
-
-The `no-cache` property can also be set globally. The global default is `false`, and the global value is used when no app-specific value is set.
-
-```shell
-dokku builder-nixpacks:set --global no-cache true
-```
-
-The default value may be set by passing an empty value for the option.
-
-```shell
-dokku builder-nixpacks:set --global no-cache
+dokku docker-options:add node-js-app build "--no-cache"
 ```
 
 ### Displaying builder-nixpacks reports for an app
@@ -115,27 +97,20 @@ dokku builder-nixpacks:report
 ```
 =====> node-js-app builder-nixpacks information
        Builder-nixpacks computed nixpackstoml path: nixpacks2.toml
-       Builder-nixpacks global nixpackstoml path:   nixpacks.toml
+       Builder-nixpacks global nixpackstoml path:
        Builder-nixpacks nixpackstoml path:          nixpacks2.toml
-       Builder-nixpacks computed no cache:          true
-       Builder-nixpacks global no cache:            false
-       Builder-nixpacks no cache:                   true
 =====> python-sample builder-nixpacks information
        Builder-nixpacks computed nixpackstoml path: nixpacks.toml
-       Builder-nixpacks global nixpackstoml path:   nixpacks.toml
+       Builder-nixpacks global nixpackstoml path:
        Builder-nixpacks nixpackstoml path:
-       Builder-nixpacks computed no cache:          false
-       Builder-nixpacks global no cache:            false
-       Builder-nixpacks no cache:
 =====> ruby-sample builder-nixpacks information
        Builder-nixpacks computed nixpackstoml path: nixpacks.toml
-       Builder-nixpacks global nixpackstoml path:   nixpacks.toml
+       Builder-nixpacks global nixpackstoml path:
        Builder-nixpacks nixpackstoml path:
-       Builder-nixpacks computed no cache:          false
-       Builder-nixpacks global no cache:            false
-       Builder-nixpacks no cache:
 ```
 
+The `nixpackstoml-path` and `global-nixpackstoml-path` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-nixpackstoml-path` key holds the effective value used at build time, falling back to the global value (where one has been set) and then to the built-in default of `nixpacks.toml`.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -145,19 +120,24 @@ dokku builder-nixpacks:report node-js-app
 ```
 =====> node-js-app builder-nixpacks information
        Builder-nixpacks computed nixpackstoml path: nixpacks2.toml
-       Builder-nixpacks global nixpackstoml path:   nixpacks.toml
+       Builder-nixpacks global nixpackstoml path:
        Builder-nixpacks nixpackstoml path:          nixpacks2.toml
-       Builder-nixpacks computed no cache:          true
-       Builder-nixpacks global no cache:            false
-       Builder-nixpacks no cache:                   true
 ```
 
 You can pass flags which will output only the value of the specific information you want. For example:
 
 ```shell
-dokku builder-nixpacks:report node-js-app --builder-nixpacks-no-cache
+dokku builder-nixpacks:report node-js-app --builder-nixpacks-nixpackstoml-path
 ```
 
 ```
-true
+nixpacks2.toml
 ```
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `nixpackstoml-path` | app + global | `nixpacks.toml` | `--builder-nixpacks-nixpackstoml-path`, `--builder-nixpacks-global-nixpackstoml-path`, `--builder-nixpacks-computed-nixpackstoml-path` | Path within the app to the `nixpacks.toml` manifest used by the nixpacks builder |

docs/deployment/builders/railpack.md

@@ -0,0 +1,152 @@
+# Railpack
+
+> [!IMPORTANT]
+> New as of 0.37.0
+
+The `railpack` builder builds apps via [Railpack](https://railpack.com/), a buildpack alternative.
+
+## Usage
+
+### Requirements
+
+Before using Railpacks, the following steps must be taken:
+
+- Install the `railpack` cli: The `railpack` cli tool is not included by default with Dokku or as a dependency. It must also be installed as shown on [this page](https://railpack.com/installation).
+- Create a `buildkit` builder: Railpack uses buildkit.
+       ```shell
+       docker run --rm --privileged -d --name buildkit moby/buildkit
+       ```
+- Set the buildkit builder: Update the `/etc/default/dokku` file to set `BUILDKIT_HOST`:
+       ```shell
+       touch /etc/default/dokku
+       echo "export BUILDKIT_HOST='docker-container://buildkit'" >> /etc/default/dokku
+       ```
+
+### Detection
+
+This builder will be auto-detected in the following case:
+
+- A `railpack.json` exists in the root of the app repository.
+
+The builder may also be selected via the `builder:set` command
+
+```shell
+dokku builder:set node-js-app selected railpack
+```
+
+### Supported languages
+
+See the [upstream railpack documentation](https://railpack.com/) for further information on what languages and frameworks are supported.
+
+### Build-time configuration variables
+
+For security reasons - and as per [Docker recommendations](https://github.com/docker/docker/issues/13490) - railpack-based deploys have variables available only during runtime.
+
+For users that require customization in the `build` phase, you may use build arguments via the [docker-options plugin](/docs/advanced-usage/docker-options.md). All environment variables set by the `config` plugin are automatically exported within the railpack build environment, and thus `--env` only requires setting a key without a value.
+
+```shell
+dokku docker-options:add node-js-app build '--env NODE_ENV'
+```
+
+Alternatively, a full value may be provided in the form of `--env KEY=VALUE`:
+
+```shell
+dokku docker-options:add node-js-app build '--env NODE_ENV=production'
+```
+
+### Changing the `railpack.json` location
+
+The `railpack.json` is expected to be found in a specific directory, depending on the deploy approach:
+
+- 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 `railpackjson-path` property:
+
+```shell
+dokku builder-railpack:set node-js-app railpackjson-path .dokku/railpack.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, the build will fail.
+
+The default value may be set by passing an empty value for the option:
+
+```shell
+dokku builder-railpack:set node-js-app railpackjson-path
+```
+
+The `railpackjson-path` property can also be set globally. The global default is `railpack.json`, and the global value is used when no app-specific value is set.
+
+```shell
+dokku builder-railpack:set --global railpackjson-path railpack2.json
+```
+
+The default value may be set by passing an empty value for the option.
+
+```shell
+dokku builder-railpack:set --global railpackjson-path
+```
+
+### Disabling cache
+
+Disable cache using the [docker-options] plugin:
+
+```shell
+dokku docker-options:add node-js-app build "--no-cache"
+```
+
+### Displaying builder-railpack reports for an app
+
+You can get a report about the app's storage status using the `builder-railpack:report` command:
+
+```shell
+dokku builder-railpack:report
+```
+
+```
+=====> node-js-app builder-railpack information
+       Builder-railpack computed railpackjson path: railpack2.json
+       Builder-railpack global railpackjson path:
+       Builder-railpack railpackjson path:          railpack2.json
+=====> python-sample builder-railpack information
+       Builder-railpack computed railpackjson path: railpack.json
+       Builder-railpack global railpackjson path:
+       Builder-railpack railpackjson path:
+=====> ruby-sample builder-railpack information
+       Builder-railpack computed railpackjson path: railpack.json
+       Builder-railpack global railpackjson path:
+       Builder-railpack railpackjson path:
+```
+
+The `railpackjson-path` and `global-railpackjson-path` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-railpackjson-path` key holds the effective value used at build time, falling back to the global value (where one has been set) and then to the built-in default of `railpack.json`.
+
+You can run the command for a specific app also.
+
+```shell
+dokku builder-railpack:report node-js-app
+```
+
+```
+=====> node-js-app builder-railpack information
+       Builder-railpack computed railpackjson path: railpack2.json
+       Builder-railpack global railpackjson path:
+       Builder-railpack railpackjson path:          railpack2.json
+```
+
+You can pass flags which will output only the value of the specific information you want. For example:
+
+```shell
+dokku builder-railpack:report node-js-app --builder-railpack-railpackjson-path
+```
+
+```
+railpack2.json
+```
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `railpackjson-path` | app + global | `railpack.json` | `--builder-railpack-railpackjson-path`, `--builder-railpack-global-railpackjson-path`, `--builder-railpack-computed-railpackjson-path` | Path within the app to the `railpack.json` manifest used by the railpack builder |

docs/deployment/continuous-integration/generic.md

@@ -11,6 +11,7 @@ Assuming a Docker image can be run as a CI task with environment variables injec
 - [gitlab-ci](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/)
 - [semaphoreci](https://semaphoreci.com/)
 - [travisci](https://travis-ci.com/)
+- [woodpecker ci](https://woodpecker-ci.org/)
 
 ## Simple Usage
 

docs/deployment/continuous-integration/github-actions.md

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Cloning repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 

docs/deployment/continuous-integration/woodpecker-ci.md

@@ -0,0 +1,29 @@
+# Woodpecker CI
+
+[Woodpecker CI](https://woodpecker-ci.org/docs/intro) can be used to automatically deploy a Dokku application via the official [dokku/ci-docker-image](https://github.com/dokku/ci-docker-image). The simplest example is as follows:
+
+```yaml
+when:
+  - event: push
+    branch: main
+
+clone:
+  git:
+    image: woodpeckerci/plugin-git
+    settings:
+      partial: false
+      depth: 0
+
+steps:
+  - name: deploy
+    image: dokku/ci-docker-image
+    environment:
+      GIT_REMOTE_URL: ssh://dokku@dokku.me:22/appname
+      SSH_PRIVATE_KEY:
+          from_secret: DOKKU_ME_SSH_DEPLOY_KEY
+    commands:
+      - dokku-deploy
+```
+
+- The standard `clone` stage is replaced with one that performs a complete clone of the repository (the default is a shallow clone, which dokku would reject).
+- A `GIT_REMOTE_URL` and a `SSH_PRIVATE_KEY` (with help of the `from_secret` directive) suffice to carry out a deployment.

docs/deployment/logs.md

@@ -124,6 +124,21 @@ The `/etc/vector` mount includes the `vector.json` configuration file, but also
 
 The final volume mount - `/var/log/dokku/apps` - may be used for users that wish to ship logs to a file on disk that may be later logrotated. This directory is owned by the `dokku` user and group, with permissions set to `0755`. At this time, log-rotation is not configured for this directory.
 
+Operators using a `file` sink are encouraged to configure rotation themselves, as Dokku will not truncate these files. A minimal `/etc/logrotate.d/dokku-app-logs` might look like:
+
+```
+/var/log/dokku/apps/*/*.log {
+  daily
+  rotate 14
+  compress
+  missingok
+  notifempty
+  copytruncate
+}
+```
+
+`copytruncate` is used because Vector holds the file open between writes.
+
 #### Stopping the Vector container
 
 Vector may be stopped via the `logs:vector-stop` command.
@@ -178,6 +193,39 @@ Setting this to an empty string will reset the version to the version currently
 dokku logs:set --global vector-image
 ```
 
+#### Attaching Vector to additional Docker networks
+
+By default, the Vector container runs with `network_mode: bridge` and can only reach app containers that are also on the default bridge network. Apps deployed onto a per-app network or a custom network - typically via `dokku network:set <app> initial-network <name>` - are not reachable from Vector over Docker's internal DNS, so sinks that need to talk to those apps directly (for example, an in-host log search service such as [Logpond](https://github.com/dokku/logpond)) would have to route traffic out through the external proxy.
+
+The global `vector-networks` property accepts a comma-separated list of Docker networks for Vector to join.
+
+```shell
+dokku logs:set --global vector-networks dokku-logs
+```
+
+Multiple networks may be specified by separating them with a comma.
+
+```shell
+dokku logs:set --global vector-networks dokku-logs,observability
+```
+
+Setting this property **replaces** the default bridge attachment: the Vector container will be on the configured user-defined networks only, not the default Docker `bridge` network. Outbound traffic continues to work through the user-defined networks' NAT, so external sinks such as Datadog or hosted HTTP endpoints remain reachable.
+
+Each network must already exist; setting a non-existent network or the reserved `bridge` value will fail. The list can be cleared by setting an empty value, which restores the default `network_mode: bridge` configuration.
+
+```shell
+dokku logs:set --global vector-networks
+```
+
+Network attachments are reconciled by `docker compose` on every `logs:vector-start`, so after changing the value the Vector container must be cycled.
+
+```shell
+dokku logs:vector-stop
+dokku logs:vector-start
+```
+
+Once attached, an app on `dokku-logs` (for example via `dokku network:set node-js-app initial-network dokku-logs`) is reachable from Vector at `<app>.<process>:<port>` over the shared network without round-tripping through the external proxy.
+
 #### Configuring a log sink
 
 Vector uses the concept of log "sinks" to send logs to a given endpoint. Log sinks may be configured globally or on a per-app basis by specifying a `vector-sink` in DSN form with the `logs:set` command. Specifying a sink value will reload any running vector container.
@@ -208,6 +256,8 @@ As with app-specific sink settings, the global value may also be cleared by sett
 dokku logs:set --global vector-sink
 ```
 
+The generated vector configuration is also rewritten whenever an app is renamed, cloned or destroyed. A renamed app keeps shipping to its sink under the new name, a cloned app gets a source of its own for the sink it inherited, and a destroyed app's source and sink are removed rather than left pointing at an endpoint that was decommissioned with the app.
+
 ##### Log Sink DSN Format
 
 The DSN form of a sink is as follows:
@@ -234,30 +284,100 @@ For some sinks - such as the `http` sink - it may be useful to use special chara
 dokku logs:set test vector-sink "http://?uri=https%3A//loggerservice.com%3A1234/%3Ftoken%3Dabc1234%26type%3Dvector"
 ```
 
+For kubernetes, it may be necessary to use template syntax - `{{ .parent.child }}` - in the sink configuration. Naively using brackets will fail due to the Helm chart install process assuming that the template should be interpreted at Helm install time vs by Vector itself. To avoid this, use `base64enc:` values (available only for top-level properties at this time). The following example shows how to use `{{ pod }}` as a value.
+
+```shell
+# encode the value with a Helm `print` statement wrapper
+encoded="$(echo '{{ print "{{ pod }}" }}' | base64)"
+# the value of encoded should be: e3sgcHJpbnQgInt7IHBvZCB9fSIgfX0K
+
+# set the value 
+dokku logs:set test vector-sink "http://?process=base64enc%3A${encoded}"
+```
+
+This will transform the value to it's encoded form when configuring Vector sinks for Kubernetes.
+
 Please read the [sink documentation](https://vector.dev/docs/reference/configuration/sinks/) for your sink of choice to configure the sink as desired.
 
+#### Configuring a cron task log sink
+
+Scheduled cron tasks run in one-off containers that carry the app's usual labels, so their output is already collected by the `vector-sink` configured for the app or globally. To send that output somewhere separate, set a `vector-cron-sink`.
+
+```shell
+dokku logs:set node-js-app vector-cron-sink "console://?encoding[codec]=text"
+```
+
+As with `vector-sink`, the value may be cleared by setting an empty value, and may also be set globally:
+
+```shell
+dokku logs:set --global vector-cron-sink "console://?encoding[codec]=text"
+```
+
+Setting a cron sink **moves** cron task output rather than copying it. Vector routes each log line to exactly one of the two sinks:
+
+| Configuration | Where cron output goes | Where all other output goes |
+|---|---|---|
+| `vector-sink` only | `vector-sink` | `vector-sink` |
+| `vector-cron-sink` only | `vector-cron-sink` | nowhere |
+| both | `vector-cron-sink` | `vector-sink` |
+
+If an app is already shipping to a metered service via `vector-sink`, adding a cron sink will stop cron output from arriving there.
+
+Events on the cron branch have two extra fields added to them, so that they can be used in sink options that support templating:
+
+- `dokku_app`: the name of the app the task belongs to
+- `dokku_cron_id`: the cron task ID, as shown by `dokku cron:list`
+
+> [!WARNING]
+> Cron task containers are removed as soon as the task exits. Vector attaches to a container after it starts, so output from tasks that finish almost immediately - a bare `echo`, for instance - may be missed. Log shipping should not be relied on as the sole record that a task ran; use an external check for that.
+
+##### Writing cron output to a file on disk
+
+The `file` sink writes to a path within the vector container. The `/var/log/dokku/apps` directory is mounted into that container from the host at the same path, so it is the correct destination for output that should survive on the host.
+
+```shell
+dokku logs:set node-js-app vector-cron-sink "file://?path=/var/log/dokku/apps/node-js-app/cron.log&encoding[codec]=text"
+```
+
+Because `path` supports templating, `dokku_cron_id` can be used to give each task its own file:
+
+```shell
+dokku logs:set node-js-app vector-cron-sink "file://?path=/var/log/dokku/apps/node-js-app/cron-{{ dokku_cron_id }}.log&encoding[codec]=text"
+```
+
+Quoting the value is required, both for the `&` separators and for the spaces inside the template.
+
+> [!WARNING]
+> Vector drops any event whose templated `path` references a field it cannot resolve. Only `dokku_app` and `dokku_cron_id` are guaranteed to exist on cron events - referencing anything else risks silently discarding log lines.
+
+Vector creates missing parent directories, and buffers writes before flushing. Set `idle_timeout_secs` to shorten that delay for infrequent tasks:
+
+```shell
+dokku logs:set node-js-app vector-cron-sink "file://?path=/var/log/dokku/apps/node-js-app/cron.log&encoding[codec]=text&idle_timeout_secs=5"
+```
+
 ##### Configuring the app label
 
-Logs shipped by vector include the label `com.dokku.app-name`, which is an alias for the app name. This can be changed via the `app-label-alias` logs property with the `logs:set` command. Specifying a new alias will reload any running vector container.
+Dokku labels every app container with `com.dokku.app-name`, and events shipped by vector carry that label as the field `label."com.dokku.app-name"`. Some sinks cannot use a field named that way - Loki label names, for instance, may only contain letters, digits and underscores - so the field can be renamed on the way to the sink via the `app-label-alias` logs property. Specifying a new alias will reload any running vector container.
 
 ```shell
-# setting the sink value in quotes is encouraged to avoid
-# issues with ampersand encoding in shell commands
-dokku logs:set node-js-app app-label-alias "app-name"
+dokku logs:set node-js-app app-label-alias "app_name"
 ```
 
+Events for `node-js-app` then carry `label.app_name` and no longer carry `label."com.dokku.app-name"`.
+
 An alias may be removed by setting an empty value, which will also reload the running vector container.
 
 ```shell
 dokku logs:set node-js-app app-label-alias
 ```
 
-Only one alias may be specified on a per-app basis at a given time.
+Only one alias may be specified on a per-app basis at a given time. Valid values start with a letter or number and may otherwise contain letters, numbers, underscores, periods and hyphens.
 
 App label aliases can also be specified globally by specifying the `--global` flag to `logs:set` with no app name specified:
 
 ```shell
-dokku logs:set --global app-label-alias "app-name"
+dokku logs:set --global app-label-alias "app_name"
 ```
 
 As with app-specific label alias settings, the global value may also be cleared by setting no value.
@@ -265,3 +385,23 @@ As with app-specific label alias settings, the global value may also be cleared
 ```shell
 dokku logs:set --global app-label-alias
 ```
+
+An app-specific value takes precedence over the global one, and is applied to that app's events whether they are shipped by the app's own `vector-sink` or by the global one.
+
+The alias only changes the shipped event. Containers are always discovered by the `com.dokku.app-name` label, so changing this property never affects which logs are collected, and a change takes effect on the next vector reload without redeploying the app. Cron events are unaffected in another respect too: `dokku_app` is read from the container label before the rename, so it holds the app name regardless of the configured alias.
+
+## Properties
+
+### Settable properties
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `logs:report`. The JSON keys emitted by `logs:report --format json` are the same names with the leading `--logs-` stripped (e.g. `max-size`, `global-max-size`, `computed-max-size`). Legacy keys with the `logs-` prefix 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 |
+|---|---|---|---|---|
+| `app-label-alias` | app + global | `com.dokku.app-name` | `--logs-app-label-alias`, `--logs-global-app-label-alias`, `--logs-computed-app-label-alias` | Field name the app name is shipped under, renamed from `com.dokku.app-name` on the event |
+| `max-size` | app + global | `10m` | `--logs-max-size`, `--logs-global-max-size`, `--logs-computed-max-size` | Maximum size of an individual log file before rotation |
+| `vector-image` | global only | _parsed from `plugins/logs/Dockerfile`_ | `--logs-global-vector-image`, `--logs-computed-vector-image` | Docker image used to run the vector log-shipper container |
+| `vector-networks` | global only | none | `--logs-global-vector-networks`, `--logs-computed-vector-networks` | Comma-separated list of docker networks the vector container is attached to |
+| `vector-cron-sink` | app + global | none | `--logs-vector-cron-sink`, `--logs-global-vector-cron-sink`, `--logs-computed-vector-cron-sink` | DSN-style sink configuration for scheduled cron task output; when set, cron output is routed here instead of to `vector-sink` |
+| `vector-sink` | app + global | none | `--logs-vector-sink`, `--logs-global-vector-sink`, `--logs-computed-vector-sink` | DSN-style sink configuration for vector (e.g. `console://` or `loki://...`) |

docs/deployment/methods/archive.md

@@ -32,3 +32,29 @@ Finally, if the archive url is specified as `--`, the archive will be fetched fr
 ```shell
 curl -sSL https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-test-app.tar | dokku git:from-archive node-js-app  --
 ```
+
+## Archive Safety
+
+Archive contents are validated before extraction to prevent path traversal and symlink escape attacks. Archives containing absolute paths, parent directory traversal entries (`..`), or symlinks pointing outside the extraction directory are rejected.
+
+The following limits can be configured via global git properties:
+
+- `archive-max-size` - maximum archive size in bytes (default: `1073741824`, 1 GiB)
+- `archive-max-files` - maximum number of entries in an archive (default: `10000`)
+
+```shell
+dokku git:set --global archive-max-size 2147483648
+dokku git:set --global archive-max-files 20000
+```
+
+Unset a property to restore the default:
+
+```shell
+dokku git:set --global archive-max-size
+```
+
+The current values can be inspected via the global git report:
+
+```shell
+dokku git:report --global
+```

docs/deployment/methods/git.md

@@ -6,14 +6,15 @@
 ```
 git:allow-host <host>                             # Adds a host to known_hosts
 git:auth <host> [<username> <password>]           # Configures netrc authentication for a given git server
+git:auth-status <host> [<username> <password>]    # Reports whether the netrc entry matches the requested state
 git:from-archive [--archive-type ARCHIVE_TYPE] <app> <archive-url> [<git-username> <git-email>] # Updates an app's git repository with a given archive file
 git:from-image [--build-dir DIRECTORY] <app> <docker-image> [<git-username> <git-email>] # Updates an app's git repository with a given docker image
 git:generate-deploy-key                           # Generates a deploy ssh key
 git:load-image [--build-dir DIRECTORY] <app> <docker-image> [<git-username> <git-email>] # Updates an app's git repository with a docker image loaded from stdin
-git:sync [--build|build-if-changes] <app> <repository> [<git-ref>] # Clone or fetch an app from remote git repo
+git:sync [--build|--build-if-changes] [--skip-deploy-branch] <app> <repository> [<git-ref>] # Clone or fetch an app from remote git repo
 git:initialize <app>                              # Initialize a git repository for an app
 git:public-key                                    # Outputs the dokku public deploy key
-git:report [<app>] [<flag>]                       # Displays a git report for one or more apps
+git:report [<app>] [<flag>|--format json]         # Displays a git report for one or more apps
 git:set <app> <key> (<value>)                     # Set or clear a git property for an app
 git:status <app>                                  # Show the working tree status for an app
 ```
@@ -163,6 +164,12 @@ When running `git:sync` without a reference, it may be useful to only build when
 dokku git:sync --build-if-changes node-js-app https://github.com/heroku/node-js-getting-started.git
 ```
 
+By default, when running `git:sync` with a git branch reference, Dokku will automatically set the `deploy-branch` property to the specified branch. To skip setting the deploy branch, specify the `--skip-deploy-branch` flag.
+
+```shell
+dokku git:sync --skip-deploy-branch node-js-app https://github.com/heroku/node-js-getting-started.git main
+```
+
 ### Initializing from private repositories
 
 > [!IMPORTANT]
@@ -185,6 +192,34 @@ dokku git:auth github.com
 
 For syncing to a private repository stored on a remote Git product such as GitHub or GitLab, Dokku's recommendation is to use a personal access token on a bot user where possible. Please see your service's documentation for information regarding the recommended best practices.
 
+The password for `git:auth` may also be provided over `STDIN` to avoid placing it on the command line:
+
+```shell
+# pipe the password into git:auth
+echo "personal-access-token" | dokku git:auth github.com username
+```
+
+#### Checking the configured auth state
+
+> [!IMPORTANT]
+> New as of 0.38.0
+
+The `git:auth-status` command reports whether the configured `netrc` entry matches a desired state without exposing the underlying file. It exits `0` when the configured state matches and `1` otherwise. This allows external tooling such as configuration management systems to perform idempotent updates without reading `$DOKKU_ROOT/.netrc` directly.
+
+```shell
+# check whether github.com is configured with the expected credentials
+dokku git:auth-status github.com username personal-access-token
+
+# check whether no credentials are configured for github.com
+dokku git:auth-status github.com
+```
+
+As with `git:auth`, the password may be provided via `STDIN`:
+
+```shell
+echo "personal-access-token" | dokku git:auth-status github.com username
+```
+
 ### Allowing remote repository hosts
 
 By default, the Dokku host may not have access to a server containing the remote repository. This can be initialized via the `git:allow-host` command.
@@ -235,3 +270,73 @@ dokku git:public-key
 ```
 
 If there is no key, an error message is shown that displays the command that can be run on the Dokku server to generate a new public/private ssh key pair.
+
+### Displaying git reports for an app
+
+You can get a report about the app's git configuration using the `git:report` command:
+
+```shell
+dokku git:report
+```
+
+```
+=====> node-js-app git information
+       Git computed archive max files: 10000
+       Git computed archive max size:  1073741824
+       Git computed deploy branch:    master
+       Git computed keep git dir:     false
+       Git deploy branch:
+       Git global archive max files:
+       Git global archive max size:
+       Git global deploy branch:
+       Git global keep git dir:
+       Git keep git dir:
+       Git rev env var:               GIT_REV
+       Git sha:                       a1b2c3d
+       Git source image:
+       Git last updated at:           1700000000
+```
+
+The bare per-app keys (`deploy-branch`, `keep-git-dir`) and the `global-<prop>` keys hold the raw per-app or global value respectively, and are empty when nothing has been set. The `computed-<prop>` keys hold 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.
+
+You can run the command for a specific app also.
+
+```shell
+dokku git:report node-js-app
+```
+
+You can pass flags which will output only the value of the specific information you want. For example:
+
+```shell
+dokku git:report node-js-app --git-deploy-branch
+```
+
+The `git:report` command also takes a `--format` flag, with the valid options including `stdout` (default) and `json`. The `json` output format can be used for automation purposes:
+
+```shell
+dokku git:report node-js-app --format json
+```
+
+The `--format` flag cannot be combined with an info flag.
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `archive-max-files` | app + global | none | `--git-global-archive-max-files`, `--git-computed-archive-max-files` | Maximum number of files allowed in an uploaded archive deploy |
+| `archive-max-size` | app + global | none | `--git-global-archive-max-size`, `--git-computed-archive-max-size` | Maximum total size of an uploaded archive deploy |
+| `deploy-branch` | app + global | `master` | `--git-deploy-branch`, `--git-global-deploy-branch`, `--git-computed-deploy-branch` | Branch name pushed by the git remote that triggers a deploy |
+| `keep-git-dir` | app + global | `false` | `--git-keep-git-dir`, `--git-global-keep-git-dir`, `--git-computed-keep-git-dir` | When `true`, retains the `.git` directory inside the build context |
+| `rev-env-var` | app + global | `GIT_REV` | `--git-rev-env-var` | Environment variable name receiving the deployed commit SHA; empty disables injection |
+| `source-image` | app + global | none | `--git-source-image` | Docker image to clone application source from when deploying from an image |
+
+### Read-only flags
+
+The following flags surface in `git:report` but are not managed by `git:set` - they are derived from repository state:
+
+| Flag | Description |
+|---|---|
+| `--git-sha` | HEAD commit SHA of the app's git repo |
+| `--git-last-updated-at` | UNIX timestamp of the last write to the deploy branch ref |

docs/deployment/methods/image.md

@@ -17,7 +17,13 @@ In the above example, Dokku will build the app as if the repository contained _o
 FROM my-registry/node-js-getting-started:latest
 ```
 
-If the specified image already exists on the Dokku host, it will not be pulled again, though this behavior may be changed using [build phase docker-options](/docs/advanced-usage/docker-options.md).
+If the specified image already exists on the Dokku host, it will not be pulled again. To force a pull even when the image exists locally, use the `--force` flag:
+
+```shell
+dokku git:from-image --force node-js-app my-registry/node-js-getting-started:latest
+```
+
+This is useful when the remote image has been updated but the tag remains the same.
 
 Triggering a build with the same arguments multiple times will result in Dokku exiting `0` early as there will be no changes detected. If the image tag is reused but the underlying image is different, it is recommended to use the image digest instead of the tag. This can be retrieved via the following command:
 

docs/deployment/remote-commands.md

@@ -71,7 +71,7 @@ All commands have the application name automatically set via the `--app` flag on
 
 The client supports several environment variables:
 
-- `DOKKU_HOST` (default: `dokku` git remote): Used to interact with a specific remote server. Can be overridden via the `--remote` flag.
+- `DOKKU_HOST` (default: `dokku` git remote): Used to interact with a specific remote server. Can be overridden via the `--remote` flag. Must specify the `--app` flag when specified.
 - `DOKKU_PORT` (default: `22`): Used to specify a port to connect to the Dokku server on.
 
 It also supports several flags (all flags unspecified here are passed as is to the server):
@@ -99,6 +99,12 @@ To list all available remotes, run `dokku remote:list`. This is equivalent to ru
 
 To add a remote, run `dokku remote:add $REMOTE_NAME dokku@dokku.me:$APP_NAME`, replacing `$REMOTE_NAME` with your desired remote name, the `$APP_NAME` with your desired app name and the host `dokku.me` with your Dokku host. This is equivalent to running `git remote add $REMOTE_NAME dokku@dokku.me:$APP_NAME`.
 
+The following remote formats are supported:
+
+- `dokku@HOSTNAME.TLD:APP_NAME`
+- `ssh://dokku@HOSTNAME.TLD/APP_NAME`
+- `ssh://dokku@HOSTNAME.TLD:HOST_PORT/APP_NAME`
+
 To remove a remote, run `dokku remote:remove $REMOTE_NAME`. This is equivalent to running `git remote remove $REMOTE_NAME`.
 
 By default, the remote in use is `dokku`. To change the remote the client uses by default, run `dokku remote:set $REMOTE_NAME`, where `$REMOTE_NAME` is the name of your desired remote. This will not check the value specified, so that remote *must* be available or errors will occur when running normal client commands. Note that specifying `--remote` when running dokku commands will override this configuration value.

docs/deployment/schedulers/docker-local.md

@@ -5,7 +5,7 @@
 
 ```
 scheduler-docker-local:report [<app>] [<flag>]              # Displays a scheduler-docker-local report for one or more apps
-scheduler-docker-local:set <app> <key> (<value>)            # Set or clear a scheduler-docker-local property for an app
+scheduler-docker-local:set [<app>|--global] <key> (<value>) # Set or clear a scheduler-docker-local property for an app or globally
 ```
 
 > [!IMPORTANT]
@@ -46,7 +46,19 @@ Once set, you may re-enable it by setting a blank value for `init-process`:
 dokku scheduler-docker-local:set node-js-app init-process
 ```
 
-All image containers with the label `org.opencontainers.image.vendor=linuxserver.io` will have the automatic init process injection force-disabled without further intervention.
+The default value may also be configured globally with the `--global` flag. Per-app values take precedence over the global value when set.
+
+```shell
+dokku scheduler-docker-local:set --global init-process false
+```
+
+The global value may also be unset by setting a blank value.
+
+```shell
+dokku scheduler-docker-local:set --global init-process
+```
+
+All image containers with the label `org.opencontainers.image.vendor=linuxserver.io` will have the automatic init process injection force-disabled without further intervention when neither an app-level nor a global value is set.
 
 ### Deploying Process Types in Parallel
 
@@ -66,6 +78,18 @@ Once set, you may reset it by setting a blank value for `parallel-schedule-count
 dokku scheduler-docker-local:set node-js-app parallel-schedule-count
 ```
 
+The default value may also be configured globally with the `--global` flag. Per-app values take precedence over the global value when set.
+
+```shell
+dokku scheduler-docker-local:set --global parallel-schedule-count 4
+```
+
+The global value may also be unset by setting a blank value.
+
+```shell
+dokku scheduler-docker-local:set --global parallel-schedule-count
+```
+
 If the value of `parallel-schedule-count` is increased and a given process type fails to schedule successfully, then any in-flight process types will continue to be processed, while all process types that have not been scheduled will be skipped before the deployment finally fails.
 
 Container scheduling output is shown in the order it is received, and thus may be out of order in case of output to stderr.
@@ -100,6 +124,57 @@ Note that increasing the value of `max_parallel` may significantly impact CPU ut
 
 See the [app.json location documentation](/docs/advanced-usage/deployment-tasks.md#changing-the-appjson-location) for more information on where to place your `app.json` file.
 
+### Displaying scheduler-docker-local reports for an app
+
+You can get a report about the app's scheduler-docker-local configuration using the `scheduler-docker-local:report` command:
+
+```shell
+dokku scheduler-docker-local:report
+```
+
+```
+=====> node-js-app scheduler-docker-local information
+       Scheduler docker local computed init process:          true
+       Scheduler docker local computed parallel schedule count:1
+       Scheduler docker local global init process:            true
+       Scheduler docker local global parallel schedule count: 1
+       Scheduler docker local init process:
+       Scheduler docker local parallel schedule count:
+```
+
+You can run the command for a specific app also.
+
+```shell
+dokku scheduler-docker-local:report node-js-app
+```
+
+You can pass flags which will output only the value of the specific information you want. For example:
+
+```shell
+dokku scheduler-docker-local:report node-js-app --scheduler-docker-local-computed-init-process
+```
+
+When run against `--global`, only the global keys are reported.
+
+```shell
+dokku scheduler-docker-local:report --global
+```
+
+The available keys are:
+
+- `--scheduler-docker-local-init-process`: the raw per-app init-process value (empty when unset).
+- `--scheduler-docker-local-computed-init-process`: the effective init-process value, computed as the per-app value if set, otherwise the global value, otherwise `true`.
+- `--scheduler-docker-local-global-init-process`: the global init-process value (defaults to `true`).
+- `--scheduler-docker-local-parallel-schedule-count`: the raw per-app parallel-schedule-count value (empty when unset).
+- `--scheduler-docker-local-computed-parallel-schedule-count`: the effective parallel-schedule-count value, computed as the per-app value if set, otherwise the global value, otherwise `1`.
+- `--scheduler-docker-local-global-parallel-schedule-count`: the global parallel-schedule-count value (defaults to `1`).
+
+The report may also be emitted as JSON using `--format json`, which is useful for external tooling that needs to distinguish a value set on the app from one that is defaulting.
+
+```shell
+dokku scheduler-docker-local:report node-js-app --format json
+```
+
 ## Scheduler Interface
 
 The following sections describe implemented scheduler functionality for the `docker-local` scheduler.
@@ -141,3 +216,12 @@ The `docker-local` scheduler supports a minimal list of resource _limits_ and _r
 
 - memory: (docker option: `--memory-reservation`) should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes). Default unit is `m` (megabytes).
     - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `init-process` | app + global | `true` | `--scheduler-docker-local-init-process`, `--scheduler-docker-local-global-init-process`, `--scheduler-docker-local-computed-init-process` | When `true`, runs containers with Docker's `--init` flag (reaping zombie processes) |
+| `parallel-schedule-count` | app + global | `1` | `--scheduler-docker-local-parallel-schedule-count`, `--scheduler-docker-local-global-parallel-schedule-count`, `--scheduler-docker-local-computed-parallel-schedule-count` | Maximum number of containers scheduled in parallel during a deploy |

docs/deployment/schedulers/k3s.md

@@ -4,19 +4,29 @@
 > New as of 0.33.0
 
 ```
-scheduler-k3s:annotations:set <app|--global> <property> (<value>) [--process-type PROCESS_TYPE] <--resource-type RESOURCE_TYPE>, Set or clear an annotation for a given app/process-type/resource-type combination
-scheduler-k3s:autoscaling-auth:set <app|--global> <trigger> [<--metadata key=value>...], Set or clear a scheduler-k3s autoscaling keda trigger authentication resource for an app
-scheduler-k3s:autoscaling-auth:report <app|--global> [--format stdout|json] [--include-metadata] # Displays a scheduler-k3s autoscaling auth report for an app
-scheduler-k3s:cluster-add [ssh://user@host:port]    # Adds a server node to a Dokku-managed cluster
-scheduler-k3s:cluster-list                          # Lists all nodes in a Dokku-managed cluster
-scheduler-k3s:cluster-remove [node-id]              # Removes client node to a Dokku-managed cluster
-scheduler-k3s:ensure-charts                         # Ensures the k3s charts are installed
-scheduler-k3s:initialize                            # Initializes a cluster
-scheduler-k3s:labels:set <app|--global> <property> (<value>) [--process-type PROCESS_TYPE] <--resource-type RESOURCE_TYPE>, Set or clear a label for a given app/process-type/resource-type combination
-scheduler-k3s:report [<app>] [<flag>]               # Displays a scheduler-k3s report for one or more apps
-scheduler-k3s:set [<app>|--global] <key> (<value>)  # Set or clear a scheduler-k3s property for an app or the scheduler
-scheduler-k3s:show-kubeconfig                       # Displays the kubeconfig for remote usage
-scheduler-k3s:uninstall                             # Uninstalls k3s from the Dokku server
+scheduler-k3s:annotations:set <app|--global> <property> (<value>) [--process-type PROCESS_TYPE] <--resource-type RESOURCE_TYPE> # Set or clear an annotation for a given app/process-type/resource-type combination
+scheduler-k3s:annotations:report [<app>|--global] [--format stdout|json] [--process-type PROCESS_TYPE] [--resource-type RESOURCE_TYPE] # Displays a scheduler-k3s annotations report for one or more apps
+scheduler-k3s:autoscaling-auth:set <app|--global> <trigger> [<--metadata key=value>...] # Set or clear a scheduler-k3s autoscaling keda trigger authentication resource for an app
+scheduler-k3s:autoscaling-auth:report [<app>|--global] [--format stdout|json] [--include-metadata] # Displays a scheduler-k3s autoscaling auth report for one or more apps
+scheduler-k3s:charts:report [<chart>] [--format stdout|json] # Displays a scheduler-k3s chart override report
+scheduler-k3s:charts:set <chart-name.property> (<value>) # Set or clear a chart-specific helm value
+scheduler-k3s:cluster:add [--profile PROFILE] [--role ROLE] [--insecure-allow-unknown-hosts] [--server-ip SERVER_IP] [--taint-scheduling] [--kubelet-args KUBELET_ARGS] <ssh://user@host:port> # Adds a server node to a Dokku-managed cluster
+scheduler-k3s:cluster:list [--format json|stdout] # Lists all nodes in a Dokku-managed cluster
+scheduler-k3s:cluster:remove [node-id] # Removes client node to a Dokku-managed cluster
+scheduler-k3s:ensure-charts # Ensures the k3s charts are installed
+scheduler-k3s:initialize [--server-ip SERVER_IP] [--taint-scheduling] [--kubelet-args KUBELET_ARGS] # Initializes a cluster
+scheduler-k3s:labels:set <app|--global> <property> (<value>) [--process-type PROCESS_TYPE] <--resource-type RESOURCE_TYPE> # Set or clear a label for a given app/process-type/resource-type combination
+scheduler-k3s:labels:report [<app>|--global] [--format stdout|json] [--process-type PROCESS_TYPE] [--resource-type RESOURCE_TYPE] # Displays a scheduler-k3s labels report for one or more apps
+scheduler-k3s:node-sysctls:set <sysctl> (<value>) [--global|--profile PROFILE] # Set or clear a node-level kernel sysctl for unprofiled nodes or a single node profile
+scheduler-k3s:node-sysctls:report [--format stdout|json] # Displays the node-level kernel sysctls applied to each scope
+scheduler-k3s:preview <app> [--context N] [--show-secrets] [--show-secrets-decoded] # Displays a diff between the current and next deployment for an app
+scheduler-k3s:profiles:add <profile> [--role ROLE] [--insecure-allow-unknown-hosts] [--taint-scheduling] [--kubelet-args KUBELET_ARGS] # Adds a node profile to the k3s cluster
+scheduler-k3s:profiles:list [--format json|stdout] # Lists all node profiles in the k3s cluster
+scheduler-k3s:profiles:remove <profile> # Removes a node profile from the k3s cluster
+scheduler-k3s:report [<app>|--global] [--format stdout|json] [<flag>] # Displays a scheduler-k3s report for one or more apps
+scheduler-k3s:set <app|--global> <property> (<value>) # Set or clear a scheduler-k3s property for an app or globally
+scheduler-k3s:show-kubeconfig # Displays the kubeconfig for remote usage
+scheduler-k3s:uninstall # Uninstalls k3s from the Dokku server
 ```
 
 > [!NOTE]
@@ -70,6 +80,20 @@ Dokku can also use Traefik on cluster initialization via the [Traefik's CRDs](ht
 dokku scheduler-k3s:initialize --ingress-class traefik
 ```
 
+Kubelet flags for the initial server node can be supplied by passing `--kubelet-args` with a comma-separated `key=value` list. This is the only way to configure the kubelet on the node created by `scheduler-k3s:initialize`, as that node never passes through `scheduler-k3s:cluster:add`.
+
+```shell
+dokku scheduler-k3s:initialize \
+  --kubelet-args allowed-unsafe-sysctls=net.ipv6.conf.all.disable_ipv6
+```
+
+Multiple kubelet arguments can be specified in the same call by separating them with commas.
+
+```shell
+dokku scheduler-k3s:initialize \
+  --kubelet-args allowed-unsafe-sysctls=net.ipv6.conf.all.disable_ipv6,max-pods=150
+```
+
 ### Adding nodes to the cluster
 
 > [!WARNING]
@@ -77,22 +101,38 @@ dokku scheduler-k3s:initialize --ingress-class traefik
 
 #### Adding a worker node
 
-Nodes that run app workloads can be added via the `scheduler-k3s:cluster-add` command. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in worker mode. Workers are typically used to run app workloads.
+Nodes that run app workloads can be added via the `scheduler-k3s:cluster:add` command. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in worker mode. Workers are typically used to run app workloads.
 
 ```shell
-dokku scheduler-k3s:cluster-add  ssh://root@worker-1.example.com
+dokku scheduler-k3s:cluster:add  ssh://root@worker-1.example.com
+```
+
+Per-node kubelet flags can be supplied by passing `--kubelet-args` with a comma-separated `key=value` list. This is useful for tuning scheduler capacity or enforcing cluster-wide defaults at the node level.
+
+```shell
+dokku scheduler-k3s:cluster:add \
+  --kubelet-args allowed-unsafe-sysctls=net.ipv6.conf.all.disable_ipv6 \
+  ssh://root@worker-1.example.com
+```
+
+Multiple kubelet arguments can be specified in the same call by separating them with commas. The following example enables IPv4 forwarding while also increasing the pod density on the worker.
+
+```shell
+dokku scheduler-k3s:cluster:add \
+  --kubelet-args allowed-unsafe-sysctls=net.ipv6.conf.all.disable_ipv6,max-pods=150 \
+  ssh://root@worker-2.example.com
 ```
 
 If the server isn't in the `known_hosts` file, the connection will fail. This can be bypassed by setting the `--insecure-allow-unknown-hosts` flag:
 
 ```shell
-dokku scheduler-k3s:cluster-add --insecure-allow-unknown-hosts ssh://root@worker-1.example.com
+dokku scheduler-k3s:cluster:add --insecure-allow-unknown-hosts ssh://root@worker-1.example.com
 ```
 
 By default, Dokku will attempt to auto-detect the IP address of the Dokku server for the remote server to connect to. In cases where the auto-detected IP address is incorrect, an override may be specified via the `--server-ip` flag:
 
 ```shell
-dokku scheduler-k3s:cluster-add --server-ip 192.168.20.15 ssh://root@worker-1.example.com
+dokku scheduler-k3s:cluster:add --server-ip 192.168.20.15 ssh://root@worker-1.example.com
 ```
 
 #### Adding a server node
@@ -102,28 +142,28 @@ dokku scheduler-k3s:cluster-add --server-ip 192.168.20.15 ssh://root@worker-1.ex
 
 Server nodes are typically used to replicate the cluster state, and it is recommended to have an odd number of nodes spread across several availability zones (datacenters in close proximity within a region). This allows for higher availability in the event of a cluster failure. Server nodes run control-plane services such as the traefik load balancer and the etcd backing store.
 
-Server nodes can also be added with the `scheduler-k3s:cluster-add` command by specifying `--role server`. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in server mode.
+Server nodes can also be added with the `scheduler-k3s:cluster:add` command by specifying `--role server`. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in server mode.
 
 ```shell
-dokku scheduler-k3s:cluster-add  --role server ssh://root@server-1.example.com
+dokku scheduler-k3s:cluster:add  --role server ssh://root@server-1.example.com
 ```
 
 Server nodes allow any workloads to be scheduled on them by default, in addition to the control-plane, etcd, and the scheduler itself. To avoid app workloads being scheduled on your control-plane, use the `--taint-scheduling` flag:
 
 ```shell
-dokku scheduler-k3s:cluster-add --role server --taint-scheduling ssh://root@server-1.example.com
+dokku scheduler-k3s:cluster:add --role server --taint-scheduling ssh://root@server-1.example.com
 ```
 
 If the server isn't in the `known_hosts` file, the connection will fail. This can be bypassed by setting the `--insecure-allow-unknown-hosts` flag:
 
 ```shell
-dokku scheduler-k3s:cluster-add --role server --insecure-allow-unknown-hosts ssh://root@server-1.example.com
+dokku scheduler-k3s:cluster:add --role server --insecure-allow-unknown-hosts ssh://root@server-1.example.com
 ```
 
 By default, Dokku will attempt to auto-detect the IP address of the Dokku server for the remote server to connect to. In cases where the auto-detected IP address is incorrect, an override may be specified via the `--server-ip` flag:
 
 ```shell
-dokku scheduler-k3s:cluster-add --role server --server-ip 192.168.20.15 ssh://root@server-1.example.com
+dokku scheduler-k3s:cluster:add --role server --server-ip 192.168.20.15 ssh://root@server-1.example.com
 ```
 
 #### Changing the network interface
@@ -134,109 +174,202 @@ When attaching an worker or server node, the K3s plugin will look at the IP asso
 dokku scheduler-k3s:set --global network-interface eth1
 ```
 
-### Changing deploy timeouts
+### Node Profiles
 
-By default, app deploys will timeout after 300s. To customize this value, set the `deploy-timeout` property via `scheduler-k3s:set`:
+Node profiles capture repeatable `scheduler-k3s:cluster:add` options so you can join multiple nodes with identical settings. A profile name can be specified for the `scheduler-k3s:cluster:add` command via the  `--profile <name>` flag. Any flags passed directly to `scheduler-k3s:cluster:add` override the stored values for that run.
+
+#### Listing profiles
+
+Display stored profiles to understand which roles and behaviors will be used.
+
+```shell
+dokku scheduler-k3s:profiles:list
+```
+
+```
+name            role
+awesome-profile worker
+```
+
+This command also takes an optional `--format` flag to specify a format for the output. Options include `json` and `stdout`
+
+#### Adding profiles
+
+Create or update a profile that defines how new nodes should be prepared before joining the cluster.
+
+```shell
+dokku scheduler-k3s:profiles:add edge-workers \
+  --role worker \
+  --insecure-allow-unknown-hosts \
+  --kubelet-args protect-kernel-defaults=true,eviction-hard=memory.available<200Mi
+```
+
+Profile names must be alphanumeric, may include internal dashes, cannot start/end with a dash, and must be ≤32 characters. Other than the `--server-ip` flag, all flags used for `scheduler-k3s:cluster:add` are valid for the `scheduler-k3s:profiles:add` command.
+
+#### scheduler-k3s:profiles:remove
+
+Delete a profile once it’s no longer required.
+
+```shell
+dokku scheduler-k3s:profiles:remove edge-workers
+```
+
+Removal only deletes the stored definition; nodes that already joined the cluster keep their existing configuration.
+
+#### The node profile label
+
+When a node joins via `scheduler-k3s:cluster:add --profile <name>`, Dokku labels it with `dokku.com/node-profile=<name>`. This makes a profile selectable after the fact, whether via `kubectl`, a `nodeSelector`, or a node affinity rule.
+
+```shell
+kubectl get nodes -L dokku.com/node-profile
+```
+
+Nodes added without `--profile` are not labeled, as an empty label value would be indistinguishable from a profile literally named the empty string.
+
+Two limits are worth knowing before relying on this label:
+
+- The server node never carries it. That node is created by `scheduler-k3s:initialize` and never passes through `scheduler-k3s:cluster:add`, so no profile is ever associated with it.
+- Nodes that joined before this label existed are not backfilled. Use `kubectl label node <node> dokku.com/node-profile=<name>` to set it on an existing node.
+
+### Changing deployment settings
+
+The k3s plugin provides a number of settings that can be used to managed deployments on a per-app basis. The following table outlines ones not covered elsewhere:
+
+| Name                  | Description                                       | Global Default     |
+|-----------------------|---------------------------------------------------|--------------------|
+| `deploy-timeout`      | Controls when app deploys will timeout in seconds | `300s`             |
+| `kustomize-root-path` | Controls the folder context from the deployed repository used for Kustomize | `config/kustomize` |
+| `image-pull-secrets`  | Name of a kubernetes secret used to auth against a registry | Contents of `~/.docker/config.json` from Dokku server |
+| `namespace`           | Controls the namespace used for resource creation | `default`          |
+| `rollback-on-failure` | Whether to rollback failed deploys                | `false`            |
+| `shm-size`            | Default shared memory size for pods               | Kubernetes default |
+
+All settings can be set via the `scheduler-k3s:set` command. Using `deploy-timeout` as an example:
 
 ```shell
 dokku scheduler-k3s:set node-js-app deploy-timeout 60s
 ```
 
-The default value may be set by passing an empty value for the option:
+The default value may be set by passing an empty value for the option in question:
 
 ```shell
 dokku scheduler-k3s:set node-js-app deploy-timeout
 ```
 
-The `deploy-timeout` property can also be set globally. The global default is `300s`.
+Properties can also be set globally. If not set for an app, the global value will apply.
 
 ```shell
 dokku scheduler-k3s:set --global deploy-timeout 60s
 ```
 
-The default value may be set by passing an empty value for the option.
+The global default value may be set by passing an empty value for the option.
 
 ```shell
 dokku scheduler-k3s:set --global deploy-timeout
 ```
 
-### Customizing the namespace
+### Restarting apps
 
-By default, app deploys will run against the `default` Kubernetes namespace. To customize this value, set the `namespace` property via `scheduler-k3s:set`:
+A `ps:restart` re-renders the app's Helm chart from its current configuration and upgrades the release, which is how configuration changes are picked up. Pods cycle because each Deployment's pod template carries an `app.kubernetes.io/version` annotation that changes on restart.
+
+A single process type may be targeted, in which case only that process type's pods are replaced. The rest of the release is still upgraded so configuration converges everywhere, but the untargeted Deployments keep their existing annotation and are left running:
 
 ```shell
-dokku scheduler-k3s:set node-js-app namespace lollipop
+dokku ps:restart node-js-app web
 ```
 
-The default value may be set by passing an empty value for the option:
+The app image does not need to be present on the Dokku host. Kubernetes pulls it from the registry, so a host that has reaped its local copy - as the `registry` plugin does on its own once an app has been deployed a number of times - can still restart, scale, and run one-off commands against the app. The builder type and working directory needed to render the chart are read back from the app's current Helm release when the image is unavailable locally.
+
+There is one exception. An `app.json` with a `scripts.dokku.postdeploy` task runs that task in a container on the Dokku host rather than in the cluster, and so does require the image locally. Apps without a postdeploy task are unaffected.
+
+### Displaying the scheduler report
+
+Configured properties can be inspected with the `scheduler-k3s:report` command. Without arguments, it iterates every app. Passing an app name scopes the report to that app, while `--global` reports the scheduler-wide properties on their own:
 
 ```shell
-dokku scheduler-k3s:set node-js-app namespace
+dokku scheduler-k3s:report
+dokku scheduler-k3s:report node-js-app
+dokku scheduler-k3s:report --global
 ```
 
-The `namespace` property can also be set globally. The global default is `default`.
+The output can be emitted as JSON for programmatic consumption:
 
 ```shell
-dokku scheduler-k3s:set --global namespace 60s
+dokku scheduler-k3s:report --global --format json
 ```
 
-The default value may be set by passing an empty value for the option.
+A single value can also be read directly by passing its report flag, as listed in the [settable properties](#settable-properties) table:
 
 ```shell
-dokku scheduler-k3s:set --global namespace
+dokku scheduler-k3s:report node-js-app --scheduler-k3s-computed-deploy-timeout
 ```
 
-### Enabling rollback on failure
+### Previewing deployment changes
 
-By default, app deploys do not rollback on failure. To enable this functionality, set the `rollback-on-failure` property via `scheduler-k3s:set`:
+Before triggering a deploy, the `scheduler-k3s:preview` command can be used to display a unified diff between the manifests currently stored in the live Helm release for an app and the manifests that the next deploy would roll out:
 
 ```shell
-dokku scheduler-k3s:set node-js-app rollback-on-failure true
+dokku scheduler-k3s:preview node-js-app
 ```
 
-The default value may be set by passing an empty value for the option:
+A clean redeploy with no property changes produces no output. After modifying a property that affects the main app chart (for example `dokku resource:limit --memory 256m node-js-app`), the command shows the unified diff for each changed resource. For an app that has never been deployed, the entire proposed manifest is rendered as added lines.
+
+By default each change is shown with 3 lines of surrounding context, git-diff style. The `--context` flag overrides this; pass `-1` to render the full resource around every change:
 
 ```shell
-dokku scheduler-k3s:set node-js-app rollback-on-failure
+dokku scheduler-k3s:preview node-js-app --context 0
+dokku scheduler-k3s:preview node-js-app --context -1
 ```
 
-The `rollback-on-failure` property can also be set globally. The global default is `false`.
+By default any `kind: Secret` resources have their `data` values redacted so secret bytes never appear in terminal scrollback or CI logs. Two flags adjust this behavior:
 
 ```shell
-dokku scheduler-k3s:set --global rollback-on-failure false
+dokku scheduler-k3s:preview node-js-app --show-secrets
+dokku scheduler-k3s:preview node-js-app --show-secrets-decoded
 ```
 
-The default value may be set by passing an empty value for the option.
+`--show-secrets` keeps the raw base64-encoded values, and `--show-secrets-decoded` renders them base64-decoded. In current dokku, the only Secret objects in the main app chart come from KEDA autoscaling auth resources configured via [`scheduler-k3s:autoscaling-auth:set`](#workload-autoscaling-authentication); for apps without autoscaling auth, these flags are no-ops.
+
+> [!IMPORTANT]
+> The preview only covers the main app helm release (the release named after the app). Dokku installs three auxiliary helm releases per app for config-var storage, image-pull credentials, and TLS certificates, and changes to those releases do **not** appear in this preview. In particular, a `dokku config:set` change followed by `scheduler-k3s:preview` will show no diff because the new config-var value lives in the separate `config-<app>` helm release.
+
+> [!NOTE]
+> Helm renders the proposed manifest using a client-side dry-run. The `lookup` template function returns empty values in this mode, so charts overridden via `scheduler-k3s:charts:set` that depend on `lookup` may render differently here than at actual deploy time. Dokku's bundled chart templates do not use `lookup`.
+
+### Exposing services on the network
+
+Dokku will automatically expose the `web` process as a Kubernetes Service, with all others being treated as background processes. In some cases, it may be useful to have other processes exposed as Kubernetes Service objects so as to segregate internal http endpoints from public http endpoints. This can be done by modifying the `app.json` Formation entry for your process type.
+
+```json
+{
+  "formation": {  
+    "internal-web": {
+      "service": {
+        "exposed": true
+      }
+    }
+  }
+}
+```
+
+In the above example, the `internal-web` process is exposed as a service. The `PORT` variable for the process will be set to `5000`, and a kubernetes `Service` object will be created pointing at your processes.
+
+> [!NOTE]
+> It is not possible to modify the port mapping, nor is it possible to assign domains or SSL to a non-web process.
+
+### Wildcard domains
+
+Both the `nginx` and `traefik` ingress classes route wildcard domains. Add the wildcard as a domain on the app:
 
 ```shell
-dokku scheduler-k3s:set --global rollback-on-failure
+dokku domains:add node-js-app '*.node-js-app.com'
 ```
 
-### Using image pull secrets
+A wildcard matches exactly one label, matching DNS itself, so `*.node-js-app.com` covers `api.node-js-app.com` but not `node-js-app.com` or `api.staging.node-js-app.com`. Add the apex as a separate domain if it should also be served.
 
-When authenticating against a registry via `registry:login`, the scheduler-k3s plugin will authenticate all servers in the cluster against the registry specified. If desired, an image pull secret can be used instead. To customize this value, set the `image-pull-secrets` property via `scheduler-k3s:set`:
+An exact domain always takes precedence over a wildcard, including across apps. If one app serves `*.node-js-app.com` and another serves `api.node-js-app.com`, requests for `api.node-js-app.com` are routed to the second app.
 
-```shell
-dokku scheduler-k3s:set node-js-app image-pull-secrets lollipop
-```
-
-The default value may be set by passing an empty value for the option:
-
-```shell
-dokku scheduler-k3s:set node-js-app image-pull-secrets
-```
-
-The `image-pull-secrets` property can also be set globally. The global default is empty string, and k3s will use Dokku's locally configured `~/.docker/config.json` for any private registry pulls.
-
-```shell
-dokku scheduler-k3s:set --global image-pull-secrets 60s
-```
-
-The default value may be set by passing an empty value for the option.
-
-```shell
-dokku scheduler-k3s:set --global image-pull-secrets
-```
+Only the leading label may be wildcarded. A domain such as `api.*.node-js-app.com` is treated as a literal hostname and will not match anything.
 
 ### SSL Certificates
 
@@ -254,6 +387,30 @@ dokku scheduler-k3s:set --global letsencrypt-email-stag automated@dokku.sh
 
 After enabling and rebuilding, all apps with an `http:80` port mapping will have a corresponding `https:443` added and ssl will be automatically enabled. All http requests will then be redirected to https.
 
+#### Customizing the letsencrypt email per app
+
+The `letsencrypt-email-prod` and `letsencrypt-email-stag` properties can also be set per app, overriding the global value for that app. This is useful when different apps should register their certificates under different contact emails.
+
+```shell
+dokku scheduler-k3s:set node-js-app letsencrypt-email-prod team@node-js-app.com
+```
+
+The value resolves in two steps: the app's `letsencrypt-server` selects which server (`prod` or `staging`) is used, and the matching `letsencrypt-email-<server>` property is then resolved as the app-level value, falling back to the global value. Because the two emails are per-server, an app-level `letsencrypt-email-stag` only takes effect once the app's `letsencrypt-server` is set to `staging`.
+
+When an app sets its own email for the selected server, Dokku renders a namespaced cert-manager `Issuer` into the app's own release using that email instead of pointing the app at the shared global `ClusterIssuer`. Apps without an app-level email continue to use the shared `ClusterIssuer` with the global email.
+
+The default value may be set by passing an empty value for the option, which falls the app back to the global value:
+
+```shell
+dokku scheduler-k3s:set node-js-app letsencrypt-email-prod
+```
+
+The computed value in effect for an app can be inspected via the report command:
+
+```shell
+dokku scheduler-k3s:report node-js-app --scheduler-k3s-computed-letsencrypt-email-prod
+```
+
 #### Customizing the letsencrypt server
 
 The letsencrypt integration is set to the production letsencrypt server by default. This can be changed on an app-level by setting the `letsencrypt-server` property with the `scheduler-k3s:set` command
@@ -268,7 +425,7 @@ The default value may be set by passing an empty value for the option:
 dokku scheduler-k3s:set node-js-app letsencrypt-server
 ```
 
-The `image-pull-secrets` property can also be set globally. The global default is `production`.
+The `letsencrypt-server` property can also be set globally. The global default is `production`.
 
 ```shell
 dokku scheduler-k3s:set --global letsencrypt-server staging
@@ -280,6 +437,116 @@ The default value may be set by passing an empty value for the option.
 dokku scheduler-k3s:set --global letsencrypt-server staging
 ```
 
+Automatic certificate issuance can be completely disabled for a given app by setting the `letsencrypt-server` to `false`. This is the single off switch for the app, and also disables a [manually managed issuer](#using-a-manually-managed-cert-manager-issuer).
+
+```shell
+dokku scheduler-k3s:set node-js-app letsencrypt-server false
+```
+
+The server can also be disabled globally, and then conditionally enabled on a per-app basis:
+
+```shell
+dokku scheduler-k3s:set --global letsencrypt-server false
+```
+
+Values are validated when the property is set, so a typo fails immediately rather than breaking the next deploy. The valid values are `prod`, `production`, `stag`, `staging`, and `false`.
+
+#### Using a manually managed cert-manager issuer
+
+Dokku's built-in letsencrypt integration uses an `http01` solver, which cannot issue wildcard certificates and cannot satisfy providers that require `dns01`. For those cases, create a cert-manager `Issuer` or `ClusterIssuer` yourself and point an app at it with the `cert-issuer-name` property.
+
+```shell
+dokku scheduler-k3s:set node-js-app cert-issuer-name acme-dns
+```
+
+Dokku does not create, modify, or delete the issuer - it only references it from the app's generated `Certificate`. Any cert-manager issuer works, including non-ACME ones such as `selfSigned`, `ca`, or `vault`.
+
+The issuer kind defaults to `ClusterIssuer`. To reference a namespaced `Issuer`, set the `cert-issuer-kind` property:
+
+```shell
+dokku scheduler-k3s:set node-js-app cert-issuer-kind Issuer
+```
+
+> [!WARNING]
+> A namespaced `Issuer` must exist in the same namespace as the app, as configured by the `namespace` property. cert-manager cannot reference an `Issuer` across namespaces.
+
+Unlike the letsencrypt integration, no email property is required - setting `cert-issuer-name` is itself what enables https for the app. Certificates are requested for every domain attached to the app.
+
+Both properties can also be set globally, which enables https for every app that has domains, no imported certificate, and no `letsencrypt-server false`:
+
+```shell
+dokku scheduler-k3s:set --global cert-issuer-name acme-dns
+```
+
+Certificate sources are resolved in the following order:
+
+1. A certificate imported via the `certs` plugin.
+2. `letsencrypt-server` set to `false`, which disables issuance entirely.
+3. `cert-issuer-name`, resolved app-first and then globally.
+4. The built-in letsencrypt integration.
+
+Because an empty app-level property falls back to the global value, an app cannot return to the built-in letsencrypt integration by unsetting `cert-issuer-name` while a global value is configured. Set the app's `cert-issuer-name` to the reserved value `false` instead:
+
+```shell
+dokku scheduler-k3s:set node-js-app cert-issuer-name false
+```
+
+As a consequence, an issuer literally named `false` cannot be referenced.
+
+The default value may be set by passing an empty value for the option, which falls the app back to the global value:
+
+```shell
+dokku scheduler-k3s:set node-js-app cert-issuer-name
+```
+
+If the named issuer does not exist in the cluster, Dokku emits a warning before the build starts. The warning never blocks a deploy, since the issuer may be managed independently and applied later. When a certificate fails to issue, inspect it directly:
+
+```shell
+kubectl describe certificate node-js-app-web -n default
+```
+
+##### Wildcard certificates
+
+A `dns01` issuer can issue wildcard certificates. Add the wildcard as a domain on the app, and it will be included in the generated `Certificate`:
+
+```shell
+dokku domains:add node-js-app '*.node-js-app.com'
+```
+
+See [wildcard domains](#wildcard-domains) for how a wildcard is matched against incoming requests.
+
+#### Using imported SSL certificates
+
+SSL certificates imported via the `certs` plugin can be used with the k3s scheduler. When a certificate is imported, it is automatically synced to Kubernetes as a TLS secret and will be used for the app's ingress configuration.
+
+To import a certificate:
+
+```shell
+dokku certs:add node-js-app server.crt server.key
+```
+
+When a certificate is imported:
+
+- A Kubernetes TLS secret named `tls-<app-name>` is created in the app's namespace
+- The ingress configuration is updated to use the imported certificate
+- Automatic certificate generation is disabled for the app
+
+Imported certificates take precedence over both Let's Encrypt and a [manually managed issuer](#using-a-manually-managed-cert-manager-issuer). If you have an imported certificate alongside either of those, the imported certificate will be used.
+
+To remove an imported certificate:
+
+```shell
+dokku certs:remove node-js-app
+```
+
+When a certificate is removed:
+
+- The TLS secret is deleted from Kubernetes
+- The app is automatically redeployed to update the ingress configuration
+- If Let's Encrypt is configured, automatic certificate generation will resume
+
+When an app is destroyed, any associated TLS secret is automatically cleaned up.
+
 ### Customizing Annotations and Labels
 
 > [!NOTE]
@@ -313,6 +580,8 @@ The following resource types are supported:
 - `traefik_ingressroute`
 - `traefik_middleware`
 
+Annotation keys may contain `/` (e.g. Kubernetes-style keys such as `prometheus.io/scrape`) and values may span multiple lines; both are preserved verbatim.
+
 A `ps:restart` is required after setting annotations in order to have them apply to running resources.
 
 #### Removing an annotation
@@ -326,6 +595,35 @@ dokku scheduler-k3s:annotations:set node-js-app annotation.key --resource-type d
 
 A `ps:restart` is required after removing annotations in order to remove them from running resources.
 
+#### Displaying annotations
+
+Configured annotations can be inspected with the `scheduler-k3s:annotations:report` command. Without arguments, it iterates every app and prints all annotations. Passing an app name (or `--global`) scopes the report:
+
+```shell
+dokku scheduler-k3s:annotations:report
+dokku scheduler-k3s:annotations:report node-js-app
+dokku scheduler-k3s:annotations:report --global
+```
+
+`--process-type` and `--resource-type` flags narrow the output to a specific scope, matching the flags accepted by `scheduler-k3s:annotations:set`:
+
+```shell
+dokku scheduler-k3s:annotations:report node-js-app --resource-type deployment
+dokku scheduler-k3s:annotations:report node-js-app --process-type web --resource-type deployment
+```
+
+JSON output emits flat keys of the form `{process_type}.{resource_type}.{annotation_key}`. The literal `--global` process type is rendered as `global` to keep keys free of leading dashes:
+
+```shell
+dokku scheduler-k3s:annotations:report node-js-app --format json
+```
+
+A single value can also be read directly with a flag of the form `--scheduler-k3s-annotations.{process_type}.{resource_type}.{annotation_key}`:
+
+```shell
+dokku scheduler-k3s:annotations:report node-js-app --scheduler-k3s-annotations.global.deployment.annotation.key
+```
+
 #### Setting Labels
 
 Dokku injects certain labels into each created resource by default, but it may be necessary to inject others for tighter integration with third-party tools. The `scheduler-k3s:labels:set` command can be used to perform this task. The command takes an app name and a required `--resource-type` flag.
@@ -354,6 +652,8 @@ The following resource types are supported:
 - `traefik_ingressroute`
 - `traefik_middleware`
 
+Label keys may contain `/` (e.g. Kubernetes-style keys such as `app.kubernetes.io/part-of`) and values may span multiple lines; both are preserved verbatim.
+
 A `ps:restart` is required after setting labels in order to have them apply to running resources.
 
 #### Removing a label
@@ -367,6 +667,20 @@ dokku scheduler-k3s:labels:set node-js-app label.key --resource-type deployment
 
 A `ps:restart` is required after removing labels in order to remove them from running resources.
 
+#### Displaying labels
+
+Configured labels can be inspected with the `scheduler-k3s:labels:report` command. The surface mirrors `scheduler-k3s:annotations:report`:
+
+```shell
+dokku scheduler-k3s:labels:report
+dokku scheduler-k3s:labels:report node-js-app
+dokku scheduler-k3s:labels:report --global
+dokku scheduler-k3s:labels:report node-js-app --resource-type deployment
+dokku scheduler-k3s:labels:report node-js-app --process-type web --resource-type deployment
+dokku scheduler-k3s:labels:report node-js-app --format json
+dokku scheduler-k3s:labels:report node-js-app --scheduler-k3s-labels.global.deployment.label.key
+```
+
 ### Autoscaling
 
 #### Workload Autoscaling
@@ -385,7 +699,7 @@ To enable autoscaling, use the `app.json` `formation.$PROCESS_TYPE.autoscaling`
 - `cooldown_seconds`: (default: 300) The number of seconds to wait in between each scaling event
 - `triggers`: A list of autoscaling triggers.
 
-Autoscaling triggers are passed as is to Keda, and should match the configuration keda uses for a given [scaler](https://keda.sh/docs/2.13/scalers/). Below is an example for [datadog](https://keda.sh/docs/2.13/scalers/datadog/#example-2---driving-scale-directly):
+Autoscaling triggers are passed as is to Keda, and should match the configuration keda uses for a given [scaler](https://keda.sh/docs/2.19/scalers/). Below is an example for [datadog](https://keda.sh/docs/2.19/scalers/datadog/#example-2---driving-scale-directly):
 
 ```json
 {
@@ -417,6 +731,8 @@ Each value in the `metadata` stanza can use the following interpolated strings:
 - `DOKKU_PROCESS_TYPE`: The name of the process being scaled
 - `DOKKU_APP_NAME`: The name of the app being scaled
 
+Dokku configures a Keda `fallback` (with a failure threshold of `3` and the configured replica count) on the generated `ScaledObject` so that scaling falls back to the configured replica count when a scaler's metric source becomes unavailable. Keda only allows `fallback` when at least one trigger is something other than `cpu` or `memory`, so Dokku omits the `fallback` block when every configured trigger is a `cpu` or `memory` scaler.
+
 ##### HTTP Autoscaling
 
 In addition to the built-in scalers that Keda provides, Dokku also supports Keda's HTTP Add On. This requires that the addon be properly installed and configured. For existing k3s clusters, this can be performed by the `scheduler-k3s:ensure-charts` command:
@@ -433,7 +749,6 @@ dokku scheduler-k3s:ensure-charts
 
 Once the chart is configured, an `http` trigger can be specified like so:
 
-
 ```json
 {
     "formation": {
@@ -504,15 +819,17 @@ dokku scheduler-k3s:autoscaling-auth:set $APP $TRIGGER_TYPE
 
 ##### Displaying an Authentication Resource report
 
-To see a list of authentication resources managed by Dokku, run the `scheduler-k3s:autoscaling-auth:report` command.
+To see a list of authentication resources managed by Dokku, run the `scheduler-k3s:autoscaling-auth:report` command. Without arguments, the report iterates every app; passing an app name (or `--global`) scopes the report:
 
 ```shell
+dokku scheduler-k3s:autoscaling-auth:report
 dokku scheduler-k3s:autoscaling-auth:report node-js-app
+dokku scheduler-k3s:autoscaling-auth:report --global
 ```
 
 ```
-====> $APP autoscaling-auth report
-      datadog: configured
+====> node-js-app autoscaling-auth information
+      Datadog:                       configured
 ```
 
 By default, the report will not display configured metadata - making it safe to include in Dokku report output. To include metadata and their values, add the `--include-metadata` flag:
@@ -522,13 +839,117 @@ dokku scheduler-k3s:autoscaling-auth:report node-js-app --include-metadata
 ```
 
 ```
-====> node-js-app autoscaling-auth report
+====> node-js-app autoscaling-auth information
       Datadog:                       configured
       Datadog apiKey:                1234567890
       Datadog appKey:                asdfghjkl
       Datadog datadogSite:           us5.datadoghq.com
 ```
 
+JSON output emits flat keys of the form `{trigger}.{metadata_key}` and includes the actual metadata values so export tools can reconstruct the configured state:
+
+```shell
+dokku scheduler-k3s:autoscaling-auth:report node-js-app --format json
+```
+
+A single configured metadata key can also be queried with a flag of the form `--scheduler-k3s-autoscaling-auth.{trigger}.{metadata_key}`. The returned value is masked in the same way as stdout output; use `--format json` to read the actual value:
+
+```shell
+dokku scheduler-k3s:autoscaling-auth:report node-js-app --scheduler-k3s-autoscaling-auth.datadog.apiKey
+```
+
+### Setting kernel sysctls
+
+Kernel sysctls fall into two categories, and which one a sysctl belongs to determines how it must be set.
+
+The kernel maintains a per-namespace copy of `net.*` (network namespace) as well as `kernel.shm*`, `kernel.msg*`, `kernel.sem`, and `fs.mqueue.*` (IPC namespace). These can be set on a single app's pods. Every other sysctl - including all of `vm.*`, and therefore `vm.max_map_count` - holds a single value shared by the entire machine, so it cannot be scoped to a pod and must be applied to the node itself.
+
+#### Namespaced sysctls
+
+Namespaced sysctls are set with the `docker-options` plugin, and are translated into the pod's `securityContext.sysctls`. A `ps:restart` is required to apply them.
+
+```shell
+dokku docker-options:add node-js-app deploy "--sysctl net.ipv4.ip_unprivileged_port_start=1024"
+```
+
+Passing a non-namespaced sysctl this way fails the deploy rather than silently dropping the value, since it provably cannot take effect within a pod. Note this differs from the `docker-local` scheduler, where such an option is passed straight through to `docker run`.
+
+Kubernetes further splits namespaced sysctls into a *safe* list that any pod may set, and everything else. A sysctl outside the safe list - `net.core.somaxconn`, for example - is rejected at pod admission unless the node's kubelet was started with a matching `allowed-unsafe-sysctls` value, which can be supplied at cluster initialization or when joining a node.
+
+```shell
+dokku scheduler-k3s:initialize --kubelet-args allowed-unsafe-sysctls=net.core.somaxconn
+```
+
+Dokku does not enforce the safe list itself, as its membership changes between Kubernetes releases. Only the namespaced/non-namespaced distinction, which is a property of the kernel, is validated.
+
+#### Non-namespaced sysctls
+
+Non-namespaced sysctls are a property of the node, not of any app, and are managed with the `node-sysctls:set` command. Dokku applies them via a privileged DaemonSet, so they reach every node without being told which nodes exist, cover nodes joined later, and are reapplied after a node reboots.
+
+```shell
+dokku scheduler-k3s:node-sysctls:set --global vm.max_map_count 262144
+```
+
+Omitting the value clears it.
+
+```shell
+dokku scheduler-k3s:node-sysctls:set --global vm.max_map_count
+```
+
+Clearing a sysctl stops Dokku managing it, but does not restore whatever the node had before. The last value written stays in place until that node reboots, which is how `sysctl -w` behaves everywhere else.
+
+Sysctls can also be scoped to a [node profile](#node-profiles) with `--profile`, which applies them only to nodes joined with that profile.
+
+```shell
+dokku scheduler-k3s:node-sysctls:set --profile edge-workers vm.max_map_count 524288
+```
+
+A profile scope inherits everything set globally and overrides it on conflict, so each node is covered by exactly one DaemonSet and no two ever write the same value. Note that the server node created by `scheduler-k3s:initialize` never carries a profile label, so only globally-scoped sysctls reach it.
+
+Use `node-sysctls:report` to see the resolved set for every scope.
+
+```shell
+dokku scheduler-k3s:node-sysctls:report
+```
+
+```shell
+dokku scheduler-k3s:node-sysctls:report --format json
+```
+
+The DaemonSet pulls `busybox` and `registry.k8s.io/pause` by default. On an air-gapped cluster or one behind a registry mirror, point them elsewhere:
+
+```shell
+dokku scheduler-k3s:set --global node-sysctls-image registry.internal/busybox:1.36
+```
+
+```shell
+dokku scheduler-k3s:set --global node-sysctls-pause-image registry.internal/pause:3.9
+```
+
+### Integrating Kustomize
+
+Dokku supports integration with [Kustomize](https://kustomize.io/) to further customize the generated helm charts for app deployments. For example, a `config/kustomize/kustomization.yaml` file with the following contents will override the scale for each process deployed to `3`:
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- rendered.yaml
+patches:
+- patch: |-
+    - op: replace
+      path: /spec/replicas
+      value: 3
+  target:
+      group: apps
+      version: v1
+      kind: Deployment
+```
+
+When using Kustomize with Dokku, all Kustomize-files _must_ be placed in the `config/kustomize` folder, with a `kustomization.yaml` file being the entrypoint to Kustomize. Dokku will render the helm chart to a `rendered.yaml` file, and then execute Kustomize with the `config/kustomize` folder as the context.
+
+See the [Kustomize](https://kustomize.io/) website for more details on how to use Kustomize.
+
 ### Using kubectl remotely
 
 > [!WARNING]
@@ -574,22 +995,34 @@ The default value for the `kube-context` is an empty string, and will result in
 
 ### Customizing Helm Chart Properties
 
-Dokku includes a number of helm charts by default with settings that are optimized for Dokku. That said, it may be useful to further customize the charts for a given environment. Users can customize which charts are installed by setting properties prefixed with `chart.$CHART_NAME.` with the `--global` flag.
+Dokku includes a number of helm charts by default with settings that are optimized for Dokku. That said, it may be useful to further customize the charts for a given environment. Chart overrides are managed via the `scheduler-k3s:charts:set` command, which takes a `<chart-name>.<property>` argument and a value. Chart overrides are always global because helm charts are not managed on a per-app basis.
 
 ```shell
-dokku scheduler-k3s:set --global chart.cert-manager.version 1.13.3
+dokku scheduler-k3s:charts:set cert-manager.version 1.13.3
 ```
 
 > [!NOTE]
 > Properties follow dot-notation, and are expanded according to Helm's internal logic. See the [Helm documentation](https://helm.sh/docs/helm/helm_install/#helm-install) for `helm install` for further details.
 
+Property names may contain `/` (e.g. for Kubernetes-style annotation keys such as `service.annotations.prometheus.io/scrape`) and values may span multiple lines; both are preserved verbatim.
 
-To unset a chart property, omit the value from the `scheduler-k3s:set` call:
+To unset a chart property, omit the value from the `scheduler-k3s:charts:set` call:
 
 ```shell
-dokku scheduler-k3s:set --global chart.cert-manager.version
+dokku scheduler-k3s:charts:set cert-manager.version
 ```
 
+Configured chart overrides can be inspected with the `scheduler-k3s:charts:report` command. Without an argument, it lists every chart known to Dokku along with any configured overrides; passing a chart name scopes the report to that chart:
+
+```shell
+dokku scheduler-k3s:charts:report
+dokku scheduler-k3s:charts:report cert-manager
+dokku scheduler-k3s:charts:report --format json
+```
+
+> [!NOTE]
+> The legacy form `dokku scheduler-k3s:set --global chart.<chart>.<property> <value>` continues to work but is deprecated and will be removed in a future major release. Migrate to `scheduler-k3s:charts:set` instead.
+
 A `scheduler-k3s:ensure-charts` command with the `--force` flag is required after changing any chart properties in order to have them apply. This will install all charts, not just the ones that have changed.
 
 ```shell
@@ -599,9 +1032,38 @@ dokku scheduler-k3s:ensure-charts --force
 Alternatively, a comma separated list of chart names can be specified to only force install the specified charts:
 
 ```shell
-dokku scheduler-k3s:ensure-charts --force --chart-names cert-manager
+dokku scheduler-k3s:ensure-charts --charts cert-manager
 ```
 
+### Persistent storage
+
+K3s apps mount persistent volumes through the Dokku storage plugin. A `storage:create --scheduler k3s` call provisions a PersistentVolumeClaim through a small per-entry helm release; `storage:mount <app> <name> --container-dir <path>` then attaches it to an app. Because storage entries are global, the same PVC can be mounted into multiple apps (for `ReadWriteMany` workloads) or into the same app at multiple subpaths.
+
+```shell
+# dynamically-provisioned PVC backed by Longhorn
+dokku storage:create demo-data \
+  --scheduler k3s \
+  --size 2Gi \
+  --access-mode ReadWriteOnce \
+  --storage-class-name longhorn
+
+dokku storage:mount demo demo-data --container-dir /data
+dokku storage:wait demo-data
+git push dokku master
+```
+
+For a hostPath-backed PV (no StorageClass), pass `<path>` as the second positional argument and omit `--storage-class-name`. The plugin renders both the PV and the PVC into the entry's helm release. The `--reclaim-policy` flag (`Retain` or `Delete`) controls whether the underlying PV survives `storage:destroy`. Annotations and labels set via `storage:annotations:set` and `storage:labels:set` propagate to both the PVC and the PV so backup tools (Velero, Longhorn snapshots) can find them.
+
+The legacy `storage:mount <app> <host>:<container>` colon form is rejected on k3s apps; create a named entry instead. See [Persistent Storage](/docs/advanced-usage/persistent-storage.md) for the full command reference.
+
+### Chart upgrade callbacks
+
+Some chart version transitions require side-effects that a plain `helm upgrade` cannot perform. For example, the upgrade of `keda-add-ons-http` to `0.12.2` introduces breaking changes to deployment selectors, which are immutable in Kubernetes; the chart-managed deployments must be deleted before the upgrade can proceed.
+
+Dokku handles these cases internally by registering version-targeted pre-upgrade and post-upgrade callbacks against affected charts. When `scheduler-k3s:ensure-charts` runs, the installed chart version is compared against the registered callbacks: any whose target version is greater than the currently installed version and at most the configured chart version are executed in ascending semver order, each bracketed around an upgrade to that intermediate version. A final upgrade to the configured chart version then completes the run.
+
+These callbacks are not user-configurable. Failures during a callback or its surrounding upgrade abort the run, and a subsequent `scheduler-k3s:ensure-charts` resumes from the current state.
+
 ## Scheduler Interface
 
 The following sections describe implemented and unimplemented scheduler functionality for the `k3s` scheduler.
@@ -613,6 +1075,12 @@ This plugin implements various functionality through `plugn` triggers to integra
 - `apps:clone`
 - `apps:destroy`
 - `apps:rename`
+- `docker-options`:
+    - The following docker options are translated into their kubernetes equivalents:
+        - `--cap-add`
+        - `--cap-drop`
+        - `--privileged`
+        - `--sysctl` (namespaced sysctls only, see [Setting kernel sysctls](#setting-kernel-sysctls))
 - `cron`
 - `enter`
 - `deploy`
@@ -625,6 +1093,8 @@ This plugin implements various functionality through `plugn` triggers to integra
     - Properties set by the `nginx` plugin will be respected, either by turning them into annotations or creating a custom server/location snippet that the `ingress-nginx` project can use. A `ps:restart` after changing any nginx properties is required in order to have them apply.
     - The `nginx:access-logs` and `nginx:error-logs` commands will fetch logs from one running `ingress-nginx` pod.
     - The `nginx:show-config` command will retrieve any `server` blocks associated with a domain attached to the app from one running `ingress-nginx` pod.
+- `ps:restart`
+    - Supports targeting a single process type, see [Restarting apps](#restarting-apps)
 - `ps:stop`
 - `run`
     - The `scheduler-post-run` trigger is not always triggered
@@ -643,7 +1113,39 @@ The following Dokku functionality is not implemented at this time.
 
 ### Logging support
 
-App logs for the `logs` command are fetched by Dokku from running containers via the `kubectl` cli. Persisting logs via Vector is not implemented at this time. Users may choose to configure the Vector Kubernetes integration directly by following [this guide](https://vector.dev/docs/setup/installation/platforms/kubernetes/).
+App logs for the `logs` command are fetched by Dokku from running containers via the Kubernetes api. While the `k3s` scheduler does not integrate with the `logs:vector-*` subcommands, it does respect the global `vector-sink` logs property. When that property is set, the `scheduler-k3s:ensure-charts` command can be utilized to reconfigure vector to ship kubernetes logs to the provided sink.
+
+To setup log shipping, configure the global `vector-sink` property for the `logs` plugin.. Note that this can be run before _or_ after the `scheduler-k3s:ensure-charts` command - if run before, the `scheduler-k3s:ensure-charts` subcommand will pick up the value.
+
+```shell
+dokku logs:set --global vector-sink "console://?encoding[codec]=json"
+```
+
+Next, run the `scheduler-k3s:ensure-charts` command with the `vector` chart to force the `k3s` scheduler to reconfigure vector with the specified sink:
+
+```shell
+dokku scheduler-k3s:ensure-charts --charts vector
+```
+
+Please see the [vector logs documentation](/docs/deployment/logs.md#configuring-a-log-sink) for more information on specifying vector sinks.
+
+#### Shipping cron task logs
+
+The global `vector-cron-sink` property is also respected. When set, logs from cron task pods are routed to that sink instead of the sink configured for everything else, matching the behavior described in the [cron task log sink documentation](/docs/deployment/logs.md#configuring-a-cron-task-log-sink).
+
+```shell
+dokku logs:set --global vector-cron-sink "console://?encoding[codec]=text"
+dokku scheduler-k3s:ensure-charts --charts vector
+```
+
+As with `vector-sink`, only the global property is respected - a per-app `vector-cron-sink` has no effect on the `k3s` scheduler.
+
+Cron events carry the same `dokku_app` and `dokku_cron_id` fields as they do on the `docker-local` scheduler, so sink configuration referencing them is portable between the two.
+
+Two differences are worth noting:
+
+- Templated values must be base64 encoded. Sink values containing `{{ }}` are interpreted by Helm at chart install time rather than by Vector, so the `base64enc:` form documented under [log sink DSN format](/docs/deployment/logs.md#log-sink-dsn-format) is required.
+- The `file` sink is not useful here. Vector runs as a DaemonSet agent, so a file path resolves to whichever node the agent is running on rather than to durable shared storage. Use a network sink and reference `dokku_cron_id` as a field instead of as a path component.
 
 ### Supported Resource Management Properties
 
@@ -656,3 +1158,32 @@ If unspecified for any task, the default reservation will be `.1` CPU and `128Mi
 
 > [!NOTE]
 > Cron tasks retrieve resource limits based on the computed cron task ID.
+
+## Properties
+
+### Settable properties
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `scheduler-k3s:report`. The JSON keys emitted by `scheduler-k3s:report --format json` are the same names with the leading `--scheduler-k3s-` stripped (e.g. `deploy-timeout`, `global-deploy-timeout`, `computed-deploy-timeout`). Legacy keys with the `scheduler-k3s-` prefix 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 |
+|---|---|---|---|---|
+| `cert-issuer-kind` | app + global | `ClusterIssuer` | `--scheduler-k3s-cert-issuer-kind`, `--scheduler-k3s-global-cert-issuer-kind`, `--scheduler-k3s-computed-cert-issuer-kind` | Kind of the manually managed cert-manager issuer referenced by `cert-issuer-name`, either `Issuer` or `ClusterIssuer` |
+| `cert-issuer-name` | app + global | none | `--scheduler-k3s-cert-issuer-name`, `--scheduler-k3s-global-cert-issuer-name`, `--scheduler-k3s-computed-cert-issuer-name` | Name of a manually managed cert-manager issuer to request certificates from, taking precedence over the letsencrypt integration. Set to `false` to opt an app out of a global value |
+| `deploy-timeout` | app + global | `300s` | `--scheduler-k3s-deploy-timeout`, `--scheduler-k3s-global-deploy-timeout`, `--scheduler-k3s-computed-deploy-timeout` | Timeout for a single helm install/upgrade cycle |
+| `image-pull-secrets` | app + global | none | `--scheduler-k3s-image-pull-secrets`, `--scheduler-k3s-global-image-pull-secrets`, `--scheduler-k3s-computed-image-pull-secrets` | Comma-separated list of Kubernetes secret names used to pull private images |
+| `ingress-class` | global only | `nginx` | `--scheduler-k3s-global-ingress-class`, `--scheduler-k3s-computed-ingress-class` | IngressClass name used for app ingresses (e.g. `nginx`, `traefik`) |
+| `kube-context` | global only | none | `--scheduler-k3s-global-kube-context`, `--scheduler-k3s-computed-kube-context` | Kube context name used by helm and kubectl invocations |
+| `kubeconfig-path` | global only | `/etc/rancher/k3s/k3s.yaml` | `--scheduler-k3s-global-kubeconfig-path`, `--scheduler-k3s-computed-kubeconfig-path` | Filesystem path to the kubeconfig used to talk to the cluster |
+| `kustomize-root-path` | app + global | `config/kustomize` | `--scheduler-k3s-kustomize-root-path`, `--scheduler-k3s-global-kustomize-root-path`, `--scheduler-k3s-computed-kustomize-root-path` | Path within the app to a kustomize root applied after the helm install |
+| `letsencrypt-email-prod` | app + global | none | `--scheduler-k3s-letsencrypt-email-prod`, `--scheduler-k3s-global-letsencrypt-email-prod`, `--scheduler-k3s-computed-letsencrypt-email-prod` | Contact email for production certificates. App-level values render a per-app namespaced Issuer; otherwise the shared production ClusterIssuer is used |
+| `letsencrypt-email-stag` | app + global | none | `--scheduler-k3s-letsencrypt-email-stag`, `--scheduler-k3s-global-letsencrypt-email-stag`, `--scheduler-k3s-computed-letsencrypt-email-stag` | Contact email for staging certificates. App-level values render a per-app namespaced Issuer; otherwise the shared staging ClusterIssuer is used |
+| `letsencrypt-server` | app + global | `prod` | `--scheduler-k3s-letsencrypt-server`, `--scheduler-k3s-global-letsencrypt-server`, `--scheduler-k3s-computed-letsencrypt-server` | ACME directory (`prod` or `staging`) used for app certificates, or `false` to disable all automatic certificate issuance |
+| `namespace` | app + global | `default` | `--scheduler-k3s-namespace`, `--scheduler-k3s-global-namespace`, `--scheduler-k3s-computed-namespace` | Kubernetes namespace into which the app's resources are installed |
+| `network-interface` | global only | `eth0` | `--scheduler-k3s-global-network-interface`, `--scheduler-k3s-computed-network-interface` | Host network interface used by k3s |
+| `node-sysctls-image` | global only | `busybox:1.36` | `--scheduler-k3s-global-node-sysctls-image` | Image used to apply node-level sysctls, override for air-gapped clusters |
+| `node-sysctls-pause-image` | global only | `registry.k8s.io/pause:3.9` | `--scheduler-k3s-global-node-sysctls-pause-image` | Image keeping the node sysctls daemonset pods running |
+| `rollback-on-failure` | app + global | `false` | `--scheduler-k3s-rollback-on-failure`, `--scheduler-k3s-global-rollback-on-failure`, `--scheduler-k3s-computed-rollback-on-failure` | When `true`, helm rolls back the release if a deploy fails |
+| `shm-size` | app + global | none | `--scheduler-k3s-shm-size`, `--scheduler-k3s-global-shm-size`, `--scheduler-k3s-computed-shm-size` | `/dev/shm` size override applied to app containers |
+| `token` | global only | none | `--scheduler-k3s-global-token` (masked as `*******` in default stdout output; the raw value is returned when queried via `--format json` or when this flag is requested explicitly) | Cluster join token used by `scheduler-k3s:cluster-add` |
+| `chart.<chart-name>.<property>` | global only | none | `--scheduler-k3s-global-chart.<chart-name>.<property>` (dynamic per chart/property) | Override a value injected into the helm chart named `<chart-name>` (one row per chart/property pair). Manage these via the dedicated `scheduler-k3s:charts:set` / `scheduler-k3s:charts:report` commands; the `scheduler-k3s:set`/`scheduler-k3s:report` form is deprecated. |

docs/deployment/schedulers/scheduler-management.md

@@ -45,6 +45,26 @@ The default value may be set by passing an empty value for the option.
 dokku scheduler:set --global selected
 ```
 
+### Setting the app shell
+
+The shell used for `dokku run` and `dokku enter` invocations against an app can be customized via the `shell` property. This is useful for images that ship with a non-default shell - for example, alpine-based images that only have `/bin/sh`.
+
+```shell
+dokku scheduler:set node-js-app shell sh
+```
+
+The `shell` property can also be set globally:
+
+```shell
+dokku scheduler:set --global shell sh
+```
+
+The default value (an empty string, which lets the scheduler pick its own default) may be restored by passing an empty value:
+
+```shell
+dokku scheduler:set node-js-app shell
+```
+
 ### Displaying scheduler reports for an app
 
 You can get a report about the app's scheduler status using the `scheduler:report` command:
@@ -60,14 +80,16 @@ dokku scheduler:report
        Scheduler selected: herokuish
 =====> python-sample scheduler information
        Scheduler computed selected: dockerfile
-       Scheduler global selected: herokuish
+       Scheduler global selected:
        Scheduler selected: dockerfile
 =====> ruby-sample scheduler information
-       Scheduler computed selected: herokuish
-       Scheduler global selected: herokuish
+       Scheduler computed selected: docker-local
+       Scheduler global selected:
        Scheduler selected:
 ```
 
+The `selected` and `global-selected` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-selected` 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 `docker-local`.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -76,6 +98,8 @@ dokku scheduler:report node-js-app
 
 ```
 =====> node-js-app scheduler information
+       Scheduler computed selected:  herokuish
+       Scheduler global selected:
        Scheduler selected: herokuish
 ```
 
@@ -98,7 +122,7 @@ At this time, the following dokku commands are used to implement a complete sche
 - `apps:clone`: handles app cloning
     - triggers: post-app-clone-setup
 - `cron`: generates cron tasks for the app
-    - triggers: cron-write
+    - triggers: scheduler-uses-host-cron, scheduler-cron-write
 - `deploy`: deploys app proceses and checks the status of a deploy
     - triggers: scheduler-app-status, scheduler-deploy, scheduler-is-deployed, scheduler-logs-failed
 - `enter`: enters a running container
@@ -112,7 +136,9 @@ At this time, the following dokku commands are used to implement a complete sche
 - `run:logs`: fetches running container logs
     - triggers: scheduler-run-logs
 - `ps:stop`: stops app processes
-    - triggers: scheduler-stop
+    - triggers: scheduler-stop, scheduler-cron-write
+- `ps:start`: starts app processes
+    - triggers: scheduler-deploy, scheduler-cron-write
 - `ps:inspect`: outputs inspect output for processes in an app
     - triggers: scheduler-inspect
 
@@ -121,3 +147,15 @@ Schedulers may decide to omit some functionality here, or use plugin triggers to
 Schedulers can use any tools available on the system to build the docker image, and may even be used to interact with off-server systems. The only current requirement is that the scheduler must have access to the image built in the build phase. If this is not the case, the registry plugin can be used to push the image to a registry that the scheduler software can access.
 
 Deployment tasks are currently executed directly on the primary Dokku server.
+
+## Properties
+
+### Settable properties
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `scheduler:report`. The JSON keys emitted by `scheduler:report --format json` are the same names with the leading `--scheduler-` stripped (e.g. `selected`, `global-selected`, `computed-selected`). Legacy keys with the `scheduler-` prefix 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 |
+|---|---|---|---|---|
+| `selected` | app + global | `docker-local` | `--scheduler-selected`, `--scheduler-global-selected`, `--scheduler-computed-selected` | Scheduler plugin used to deploy this app (`docker-local`, `k3s`, etc.) |
+| `shell` | app + global | none | `--scheduler-shell`, `--scheduler-global-shell`, `--scheduler-computed-shell` | Shell used by `enter`/`run` commands when entering a container |

docs/deployment/zero-downtime-deploys.md

@@ -28,7 +28,9 @@ You may both create user-defined checks for web processes using the `healthcheck
 
 ### wait-to-retire
 
-After a successful deploy, the grace period given to old containers before they are stopped/terminated is determined by the value of `wait-to-retire`. This is useful for ensuring completion of long-running HTTP connections.
+After a successful deploy, Dokku immediately sends `SIGTERM` to old containers so the application can begin a graceful shutdown (draining in-flight connections, flushing buffers, and so on) the moment proxy traffic switches to the new containers. The old containers are then left running for the `wait-to-retire` grace period before being stopped, which sends `SIGTERM` again and ultimately `SIGKILL` after `stop-timeout-seconds`. This mirrors Heroku's [dyno shutdown behavior](https://devcenter.heroku.com/articles/dyno-shutdown-behavior).
+
+The `wait-to-retire` value controls the grace period and is useful for ensuring completion of long-running HTTP connections.
 
 ```shell
 dokku checks:set node-js-app wait-to-retire 30
@@ -36,18 +38,21 @@ dokku checks:set node-js-app wait-to-retire 30
 
 Defaults to `60`.
 
-## Configuring check settings using the `config` plugin
+## Setting stop grace period
 
-There are certain settings that can be configured via environment variables:
+You can set the `stop-timeout-seconds` property on the `ps` plugin to change this value (default: `30`). See the [process management documentation](/docs/processes/process-management.md#changing-process-management-settings) for more information.
 
-- `DOKKU_DEFAULT_CHECKS_WAIT`: (default: `10`) If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running.
-- `DOKKU_DOCKER_STOP_TIMEOUT`: (default: `10`) Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands *also* respect this value. If not specified, the Docker defaults for the [`docker stop` command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.
+## Configuring check settings
 
-The following settings may also be specified in the `app.json` file, though are available as environment variables in order to ease application reuse.
+There are certain settings that can be configured via the `checks` plugin properties:
 
-- `DOKKU_CHECKS_WAIT`: (default: `5`) Wait this many seconds for the container to start before running checks.
-- `DOKKU_CHECKS_TIMEOUT`: (default: `30`) Wait this many seconds for each response before marking it as a failure.
-- `DOKKU_CHECKS_ATTEMPTS`: (default: `5`) Number of retries for to run for a specific check before marking it as a failure
+- `default-wait`: (default: `10`) If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running. Set globally via `dokku checks:set --global default-wait <value>`.
+
+The following settings may also be specified in the `app.json` file, though are available as properties in order to ease application reuse.
+
+- `wait`: (default: `5`) Wait this many seconds for the container to start before running checks. Set via `dokku checks:set <app> wait <value>`.
+- `timeout`: (default: `30`) Wait this many seconds for each response before marking it as a failure. Set via `dokku checks:set <app> timeout <value>`.
+- `attempts`: (default: `5`) Number of retries for to run for a specific check before marking it as a failure. Set via `dokku checks:set <app> attempts <value>`.
 
 ## Skipping and Disabling Checks
 
@@ -62,10 +67,6 @@ dokku checks:skip node-js-app worker,web
 
 ```
 -----> Skipping zero downtime for app's (node-js-app) proctypes (worker,web)
------> Unsetting node-js-app
------> Unsetting DOKKU_CHECKS_DISABLED
------> Setting config vars
-       DOKKU_CHECKS_SKIPPED: worker,web
 ```
 
 Zero downtime checks can also be disabled completely. This will stop old containers *before* new ones start, which may result in broken connections and downtime if your application fails to boot properly.
@@ -76,10 +77,6 @@ dokku checks:disable node-js-app worker
 
 ```
 -----> Disabling zero downtime for app's (node-js-app) proctypes (worker)
------> Setting config vars
-       DOKKU_CHECKS_DISABLED: worker
------> Setting config vars
-       DOKKU_CHECKS_SKIPPED: web
 ```
 
 ### Displaying checks reports for an app
@@ -98,22 +95,24 @@ dokku checks:report
        Checks disabled list: none
        Checks skipped list: none
        Checks computed wait to retire: 60
-       Checks global wait to retire: 60
+       Checks global wait to retire:
        Checks wait to retire:
 =====> python-app checks information
        Checks disabled list: none
        Checks skipped list: none
        Checks computed wait to retire: 60
-       Checks global wait to retire: 60
+       Checks global wait to retire:
        Checks wait to retire:
 =====> ruby-app checks information
        Checks disabled list: _all_
        Checks skipped list: none
        Checks computed wait to retire: 60
-       Checks global wait to retire: 60
+       Checks global wait to retire:
        Checks wait to retire:
 ```
 
+The `wait-to-retire` and `global-wait-to-retire` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-wait-to-retire` 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 `60`.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -123,10 +122,10 @@ dokku checks:report node-js-app
 ```
 =====> node-js-app checks information
        Checks disabled list: none
-       Checks skipped list: none   
+       Checks skipped list: none
        Checks computed wait to retire: 60
-       Checks global wait to retire: 60
-       Checks wait to retire:       
+       Checks global wait to retire:
+       Checks wait to retire:
 ```
 
 You can pass flags which will output only the value of the specific information you want. For example:
@@ -266,3 +265,11 @@ dokku checks:run node-js-app web.3
 -----> Running pre-flight checks
 Invalid container id specified (APP.web.3)
 ```
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `wait-to-retire` | app + global | `60` | `--checks-wait-to-retire`, `--checks-global-wait-to-retire`, `--checks-computed-wait-to-retire` | Seconds to wait between deploying the new container and stopping the old one |

docs/development/architecture.md

@@ -0,0 +1,316 @@
+# Dokku Architecture
+
+This document provides a developer-focused overview of Dokku's internal architecture. It is intended for contributors who want to understand how Dokku works under the hood before diving into the codebase.
+
+## High-Level Architecture
+
+Dokku is a Docker-powered Platform as a Service (PaaS) that provides a Heroku-like deployment experience. The following diagram shows the main components and their interactions:
+
+```
++------------------+
+|     User/Client  |
++--------+---------+
+         |
+         | SSH / git push
+         v
++--------+---------+
+|   dokku binary   |
+|  (bash script)   |
++--------+---------+
+         |
+         | parse_args / execute_dokku_cmd
+         v
++--------+---------+
+|   Plugin System  |
+|      (plugn)     |
++--------+---------+
+         |
+         | triggers / subcommands
+         v
++--------+---------+     +------------------+
+|  Core Plugins    |---->|  Docker / K8s    |
+|  (apps, git,     |     |    Runtime       |
+|   config, etc.)  |     +------------------+
++------------------+
+```
+
+**Key components:**
+
+- **dokku binary**: The main entry point (`/dokku`), a bash script that handles authentication, argument parsing, and routes commands to plugins
+- **Plugin System**: Uses [plugn](https://github.com/dokku/plugn) to execute triggers and discover commands
+- **Core Plugins**: Implement all Dokku functionality (apps, git, config, builders, schedulers, proxies, etc.)
+- **Runtime**: Docker (default via `scheduler-docker-local`) or Kubernetes (via `scheduler-k3s`)
+
+## Directory Structure
+
+### Source Tree
+
+```
+dokku/
+├── dokku                 # Main CLI entry point (bash script)
+├── plugins/              # All plugin source code
+│   ├── apps/            # App management
+│   ├── git/             # Git push handling
+│   ├── config/          # Environment variables
+│   ├── builder-*/       # Build backends (herokuish, pack, dockerfile, etc.)
+│   ├── scheduler-*/     # Deployment schedulers (docker-local, k3s)
+│   ├── *-vhosts/        # Proxy implementations (nginx, traefik, caddy, etc.)
+│   └── common/          # Shared functions and utilities
+├── docs/                 # Documentation (markdown)
+├── debian/               # Debian packaging files
+├── contrib/              # Installation scripts and helpers
+└── tests/                # Integration tests (bats)
+```
+
+### Runtime Directories
+
+When Dokku is installed, it creates the following directory structure:
+
+```
+/var/lib/dokku/
+├── core-plugins/         # Core plugin binaries (installed from source)
+│   ├── available/       # All available core plugins
+│   └── enabled/         # Symlinks to enabled plugins
+├── plugins/              # Community plugins
+│   ├── available/
+│   └── enabled/
+└── data/                 # Plugin data storage
+    └── <plugin>/        # Per-plugin data
+        └── <app>/       # Per-app properties
+
+$DOKKU_ROOT (~dokku by default)
+├── <app>/               # Per-app data
+│   ├── refs/           # Git refs
+│   ├── HEAD            # Current git HEAD
+│   ├── tls/            # SSL certificates
+│   └── ...             # Other app-specific files
+└── .dokkurc/            # Global configuration overrides
+```
+
+### Plugin Directory Layout
+
+Each plugin follows a consistent structure:
+
+```
+plugins/<plugin-name>/
+├── plugin.toml           # Plugin metadata (description, version)
+├── commands              # Help output and catch-all command handler
+├── subcommands/          # Individual command implementations
+│   ├── default          # Default command (e.g., `dokku apps`)
+│   └── <command>        # Named commands (e.g., `dokku apps:create`)
+├── functions             # Public functions for other plugins to source
+├── internal-functions    # Private functions
+├── triggers.go           # Go-based trigger implementations
+├── *.go                  # Additional Go code
+└── Makefile              # Build configuration
+```
+
+## Plugin System Architecture
+
+Dokku's functionality is entirely implemented through plugins. This architecture provides:
+
+- **Extensibility**: Add new features without modifying core code
+- **Loose coupling**: Plugins communicate via well-defined triggers
+- **Composability**: Mix and match builders, schedulers, and proxies
+
+### Plugin Communication via Triggers
+
+Plugins communicate through the **trigger system** powered by [plugn](https://github.com/dokku/plugn). When a trigger is fired, plugn executes matching scripts from all enabled plugins:
+
+```
++---------------+     plugn trigger     +---------------+
+|    Plugin A   | ------------------->  |    Plugin B   |
+| (fires event) |    "post-deploy"      | (listens for  |
++---------------+                       |    event)     |
+                                        +---------------+
+                                              |
+                                              v
+                                        +---------------+
+                                        |    Plugin C   |
+                                        | (also listens)|
+                                        +---------------+
+```
+
+**Trigger execution flow:**
+
+1. A plugin calls `plugn trigger <trigger-name> [args...]`
+2. plugn searches `$PLUGIN_ENABLED_PATH/*/` for files named `<trigger-name>`
+3. Each matching executable is run with the provided arguments
+4. Triggers can return data via stdout or signal errors via exit codes
+
+**Key trigger categories:**
+
+| Category | Examples | Purpose |
+|----------|----------|---------|
+| App lifecycle | `post-create`, `pre-delete`, `post-deploy` | React to app events |
+| Build | `builder-detect`, `pre-build`, `builder-build` | Control build process |
+| Deploy | `scheduler-deploy`, `check-deploy` | Manage deployments |
+| Proxy | `proxy-build-config`, `nginx-pre-reload` | Configure reverse proxy |
+| Git | `git-pre-pull`, `receive-app` | Handle git operations |
+
+For the complete list of triggers, see [Plugin Triggers](/docs/development/plugin-triggers.md).
+
+### Calling Triggers from Go Code
+
+Go-based plugins use the `common.CallPlugnTrigger` function:
+
+```go
+result, err := common.CallPlugnTrigger(common.PlugnTriggerInput{
+    Trigger: "post-deploy",
+    Args:    []string{appName, port, ip, imageTag},
+})
+```
+
+## Command Flow
+
+When a user runs a command like `dokku apps:list`, here's what happens:
+
+```
+User runs: ssh dokku@host apps:list
+                    |
+                    v
++-------------------+-------------------+
+|           dokku bash script           |
+|  1. Source /etc/default/dokku         |
+|  2. Set DOKKU_ROOT, PLUGIN_PATH       |
+|  3. Source common/functions           |
+|  4. Call parse_args()                 |
+|  5. Check user permissions            |
++-------------------+-------------------+
+                    |
+                    v
++-------------------+-------------------+
+|          execute_dokku_cmd()          |
+|  1. Handle plugin aliases             |
+|  2. Check for subcommands/default     |
+|  3. Check for subcommands/<cmd>       |
+|  4. Fall back to commands scripts     |
++-------------------+-------------------+
+                    |
+                    v
++-------------------+-------------------+
+|  plugins/apps/subcommands/list        |
+|  (executes the actual command)        |
++-------------------+-------------------+
+```
+
+**Command resolution order:**
+
+1. Check `$PLUGIN_ENABLED_PATH/<plugin>/subcommands/default` for the default command
+2. Check `$PLUGIN_ENABLED_PATH/<plugin>/subcommands/<command>` for named commands
+3. Iterate through all `$PLUGIN_ENABLED_PATH/*/commands` scripts as fallback
+
+## Deployment Pipeline
+
+When code is pushed via `git push dokku@host:myapp`, Dokku executes a multi-stage pipeline:
+
+```
++-------------+    +-------------+    +-------------+    +-------------+
+|   Receive   |--->|    Build    |--->|   Release   |--->|   Deploy    |
++-------------+    +-------------+    +-------------+    +-------------+
+      |                  |                  |                  |
+      v                  v                  v                  v
+  git-hook          builder-detect    builder-release    scheduler-deploy
+  receive-app       pre-build                            core-post-deploy
+  post-extract      builder-build                        post-deploy
+```
+
+### Stage 1: Receive
+
+The git receive stage handles the incoming push and prepares the source code:
+
+1. `git-hook` receives the push and validates the branch
+2. `receive-app` trigger is fired
+3. Source code is extracted to a temporary directory
+4. `post-extract` trigger allows modification of source
+
+### Stage 2: Build
+
+The build stage creates a Docker image from the source:
+
+1. `builder-detect` determines the builder type (herokuish, pack, dockerfile, etc.)
+2. `pre-build` trigger runs pre-build hooks
+3. `builder-build` creates the Docker image
+4. `post-build` trigger runs post-build hooks
+
+### Stage 3: Release
+
+The release stage prepares the image for deployment:
+
+1. `pre-release-builder` allows image modifications
+2. `builder-release` sets environment variables in the image
+3. `post-release-builder` runs final release hooks
+
+### Stage 4: Deploy
+
+The deploy stage starts containers and configures networking:
+
+1. `scheduler-deploy` starts new containers
+2. `check-deploy` runs health checks
+3. `core-post-deploy` switches traffic to new containers
+4. `post-deploy` runs deployment tasks
+5. Old containers are retired
+
+## State Management
+
+Dokku uses a file-based state system for simplicity and transparency.
+
+### Property System
+
+Plugin-specific configuration is stored in the property system:
+
+```
+/var/lib/dokku/data/<plugin>/<app>/<property>
+```
+
+Properties are managed via helper functions:
+
+```bash
+# Shell
+fn-plugin-property-write "git" "$APP" "deploy-branch" "main"
+fn-plugin-property-get "git" "$APP" "deploy-branch"
+```
+
+```go
+// Go
+common.PropertyWrite("git", appName, "deploy-branch", "main")
+common.PropertyGet("git", appName, "deploy-branch")
+```
+
+### Per-App Data
+
+Application-specific data sometimes lives in `$DOKKU_ROOT/<app>/`:
+
+- `refs/` - Git references
+- `tls/` - SSL certificates
+- `ENV` - Environment file
+- Container IDs, port mappings, etc.
+
+All non-git code is being migrated to the property system.
+
+### Global Configuration
+
+Global settings can be configured via:
+
+- `/etc/default/dokku` - System-level defaults
+- `$DOKKU_ROOT/dokkurc` - User-level configuration
+- `$DOKKU_ROOT/.dokkurc/*` - Additional configuration files
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| **Plugin-based architecture** | Enables extensibility without modifying core code. Community plugins can add databases, caching, and other services. |
+| **Bash + Go hybrid** | Bash for orchestration and simple commands; Go for performance-critical operations and complex logic. |
+| **Trigger system** | Loose coupling between plugins. Plugins don't need to know about each other; they just fire and respond to events. |
+| **File-based state** | Simple, transparent, and easy to debug. No database dependency. State can be inspected with standard Unix tools. |
+| **Docker as foundation** | Leverages Docker's container runtime, networking, and image management. Allows multiple scheduler backends. |
+
+## Further Reading
+
+- [Plugin Creation](/docs/development/plugin-creation.md) - How to create custom plugins
+- [Plugin Triggers](/docs/development/plugin-triggers.md) - Complete list of available triggers
+- [Testing](/docs/development/testing.md) - How to test Dokku and plugins
+- [Application Deployment](/docs/deployment/application-deployment.md) - User-facing deployment guide
+- [Builder Management](/docs/deployment/builders/builder-management.md) - Available build backends
+- [Scheduler Management](/docs/deployment/schedulers/scheduler-management.md) - Available scheduler backends

docs/development/plugin-triggers.md

@@ -119,6 +119,21 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `app-json-is-valid`
+
+- Description: Checks to see if the provided app.json file is valid
+- Invoked by: Appjson extraction during deployment
+- Arguments: `$APP $APP_JSON_PATH`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `app-maybe-create`
 
 - Description: Creates an app (gated by whether this is globally enabled or not)
@@ -372,6 +387,66 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `certs-get`
+
+- Description: Returns the certificate or key content for an app
+- Invoked by: `scheduler-k3s`
+- Arguments: `$APP $KEY_TYPE`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+# Returns the certificate or key content for an app
+# KEY_TYPE should be "crt" or "key"
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+APP="$1"; KEY_TYPE="$2"
+APP_SSL_PATH="$DOKKU_ROOT/$APP/tls"
+
+if [[ "$KEY_TYPE" == "crt" ]]; then
+  cat "$APP_SSL_PATH/server.crt"
+elif [[ "$KEY_TYPE" == "key" ]]; then
+  cat "$APP_SSL_PATH/server.key"
+fi
+```
+
+### `certs-remove`
+
+- Description: Removes the SSL cert/key pair from an app and fires the `post-certs-remove` and `post-domains-update` triggers. Fails if no app-specific SSL endpoint is defined.
+- Invoked by:
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+# Removes the SSL endpoint for an app
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+APP="$1"
+
+dokku certs:remove "$APP"
+```
+
+### `certs-set`
+
+- Description: Installs an SSL cert/key pair onto an app and fires the `post-certs-update` and `post-domains-update` triggers. `$CRT_FILE` and `$KEY_FILE` must be paths to readable PEM-encoded files.
+- Invoked by:
+- Arguments: `$APP $CRT_FILE $KEY_FILE`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+# Installs a cert/key pair for an app
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+APP="$1"; CRT_FILE="$2"; KEY_FILE="$3"
+
+dokku certs:add "$APP" "$CRT_FILE" "$KEY_FILE"
+```
+
 ### `check-deploy`
 
 - Description: Allows you to run checks on a deploy before Dokku allows the container to handle requests.
@@ -506,6 +581,36 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `config-migrate-env`
+
+- Description: Drains the pre-0.38 `$DOKKU_ROOT/ENV` and `$DOKKU_ROOT/<app>/ENV` files into the config property path, removing each file once it has been drained. A file found at the old path after its migration has been recorded is never imported: the config path holds every change made since, so the file is removed when it agrees with the current config and otherwise moved aside to `ENV.migrated`. Idempotent, and safe to call from an install trigger that runs before the config plugin's own.
+- Invoked by: `common` when migrating deprecated config vars to plugin properties, checks plugin
+- Arguments: none
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+plugn trigger config-migrate-env
+```
+
+### `config-set`
+
+- Description: Sets one or more config values for an app without restarting (when --no-restart flag is specified)
+- Invoked by: app-json plugin
+- Arguments: `[--no-restart] $APP $KEY1=VALUE1 [$KEY2=VALUE2 ...]`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `core-post-deploy`
 
 > To avoid issues with community plugins, this plugin trigger should be used _only_ for core plugins. Please avoid using this trigger in your own plugins.
@@ -567,7 +672,7 @@ APP="$1"; PROPERTY="$2"
 
 ### `cron-entries`
 
-- Description: Allows injecting cron entries into the written out scheduled cron task list. Each entry is newline delimited, and individual entries come in the form `$SCHEDULE;$FULL_COMMAND;$ARBITRARY_DATA`. Individual implementations of cron writing can decide whether and how to include these cron entries. The `ARBITRARY_DATA` includes the log file path for the basic `docker-local` cron implementation.
+- Description: Allows injecting cron tasks into the written out scheduled cron task list. Each entry is newline delimited, and individual tasks come in the form `$SCHEDULE;$FULL_COMMAND;$ARBITRARY_DATA`. Individual implementations of cron writing can decide whether and how to include these cron tasks. The `ARBITRARY_DATA` includes the log file path for the basic `docker-local` cron implementation.
 - Invoked by:
 - Arguments: `$DOKKU_SCHEDULER`
 - Example:
@@ -583,22 +688,6 @@ DOKKU_SCHEDULER="$1"
 # TODO
 ```
 
-### `cron-write`
-
-- Description: Force triggers writing out cron entries
-- Invoked by:
-- Arguments:
-- Example:
-
-```shell
-#!/usr/bin/env bash
-
-set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
-source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
-
-# TODO
-```
-
 ### `dependencies`
 
 - Description: Used to install system-level dependencies.
@@ -771,7 +860,7 @@ APP="$1"; IMAGE_SOURCE_TYPE="$2"
 
 ### `docker-args-process-deploy`
 
-- Description: `$PROC_TYPE` may be set to magic `_all_` process type to signify global docker deploy options.
+- Description: emits docker arguments scoped to a specific Procfile process type. The `docker-options` plugin implements this trigger to surface options registered via `docker-options:add --process <PROC>`. `$PROC_TYPE` may be empty (or set to the magic `_default_` value) to signify default-scope docker deploy options.
 - Invoked by: `dokku deploy`
 - Arguments: `$APP $IMAGE_SOURCE_TYPE $IMAGE_TAG [$PROC_TYPE $CONTAINER_INDEX]`
 - Example:
@@ -1266,6 +1355,8 @@ esac
 
 The default templates are viewable here: [plugins/nginx-vhosts/templates/](https://github.com/dokku/dokku/tree/master/plugins/nginx-vhosts/templates)
 
+Overriding the `validate-config` template is the supported way to make deploy-time pre-validation aware of directives from nginx modules that the host loads via `load_module` in its global config. As implementing this trigger requires a [custom plugin](/docs/development/plugin-creation.md), see [Custom nginx modules](/docs/appendices/file-formats/nginx-conf-sigil.md#custom-nginx-modules) for a complete example.
+
 ### `nginx-dokku-template-source`
 
 - Description: Return the path to a `sigil` template that should be used to generate the `dokku.conf` nginx configuration file.
@@ -1700,7 +1791,7 @@ curl "http://httpstat.us/200"
 ### `post-domains-update`
 
 - Description: Allows you to run commands once the domain for an app has been updated. It also sends in the command that has been used. This can be "add", "clear" or "remove". The third argument will be the optional list of domains
-- Invoked by: `dokku domains:add`, `dokku domains:clear`, `dokku domains:remove`, `dokku domains:set`
+- Invoked by: `dokku domains:add`, `dokku domains:clear`, `dokku domains:remove`, `dokku domains:reset`, `dokku domains:set`
 - Arguments: `$APP` `action name` `domains`
 - Example:
 
@@ -2051,7 +2142,9 @@ CMD="cat > gm && \
   dpkg -s graphicsmagick &>/dev/null || \
   (apt-get update -qq && apt-get -qq -y --no-install-recommends install graphicsmagick && apt-get clean)"
 
-CID=$(docker run $DOKKU_GLOBAL_RUN_ARGS -i -a stdin $IMAGE /bin/bash -c "$CMD")
+CID_FILE=/tmp/cid-file
+docker run $DOKKU_GLOBAL_RUN_ARGS -i -a stdin --cidfile /tmp/cid-file "$IMAGE" /bin/bash -c "$CMD"
+CID="$(cat "$CID_FILE")"
 test $(docker wait $CID) -eq 0
 DOCKER_COMMIT_LABEL_ARGS=("--change" "LABEL org.label-schema.schema-version=1.0" "--change" "LABEL org.label-schema.vendor=dokku" "--change" "LABEL com.dokku.app-name=$APP")
 docker commit "${DOCKER_COMMIT_LABEL_ARGS[@]}" $CID $IMAGE >/dev/null
@@ -2443,22 +2536,42 @@ DOKKU_SCHEDULER="$1"; APP="$2";
 # TODO
 ```
 
-### `scheduler-deploy`
+### `scheduler-cron-write`
 
 > [!WARNING]
 > The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
-- Description: Allows you to run scheduler commands when an app is deployed
-- Invoked by: `dokku deploy`
-- Arguments: `$DOKKU_SCHEDULER $APP $IMAGE_TAG`
+- Description: Force triggers writing out cron tasks. Arguments are optional. The `cron` plugin implements this for host-crontab schedulers (regenerating the whole `dokku` user crontab when the scheduler uses host cron or when no scheduler is given); self-managed schedulers such as `k3s` implement it to update their own cron backend.
+- Invoked by: `ps:start`, `ps:stop`, `cron:set`, `apps:destroy`
+- Arguments: `$DOKKU_SCHEDULER $APP`
 - Example:
 
 ```shell
 #!/usr/bin/env bash
 
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
-DOKKU_SCHEDULER="$1"; APP="$2"; IMAGE_TAG="$3";
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+
+# TODO
+```
+
+### `scheduler-deploy`
+
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
+> between minor releases until the 1.0 release.
+
+- Description: Allows you to run scheduler commands when an app is deployed. `$PROCESS_TYPE` is empty for a normal deploy and set when a single process type is targeted, as by `dokku ps:restart <app> <process-type>`, in which case only that process type should be redeployed.
+- Invoked by: `dokku deploy`
+- Arguments: `$DOKKU_SCHEDULER $APP $IMAGE_TAG $PROCESS_TYPE`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+DOKKU_SCHEDULER="$1"; APP="$2"; IMAGE_TAG="$3"; PROCESS_TYPE="$4";
 
 # TODO
 ```
@@ -2588,6 +2701,7 @@ DOKKU_SCHEDULER="$1"; APP="$2";
 > [!WARNING]
 > The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
+
 - Description: Allows you to run scheduler commands when retrieving failed container logs
 - Invoked by: `dokku nginx:access-logs` and `dokku nginx:error-logs`
 - Arguments: `$DOKKU_SCHEDULER $APP $PROXY_TYPE $LOG_TYPE $TAIL $NUM_LINES`
@@ -2783,6 +2897,26 @@ DOKKU_SCHEDULER="$1"; APP="$2"; CONTAINER="$3"; TAIL="$4"; PRETTY_PRINT="$5"; NU
 # TODO
 ```
 
+### `scheduler-run-retire`
+
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
+> between minor releases until the 1.0 release.
+
+- Description: Allows you to retire containers started by the `run` and `cron:run` commands that have exceeded their active deadline
+- Invoked by: `dokku run:retire`, `dokku ps:retire`
+- Arguments: `$DOKKU_SCHEDULER $APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+DOKKU_SCHEDULER="$1"; APP="$2";
+
+# TODO
+```
+
 ### `scheduler-run-stop`
 
 > [!WARNING]
@@ -2823,20 +2957,75 @@ DOKKU_SCHEDULER="$1"; APP="$2"; REMOVE_CONTAINERS="$3";
 # TODO
 ```
 
-### `storage-list`
+### `storage-list` (deprecated)
 
-- Description: Returns a list of storage mounts
-- Invoked by: `dokku storage:list` and `dokku deploy`
+> [!WARNING]
+> Deprecated as of 0.38.0. The trigger handler still functions for back-compat
+> with external plugins but emits a deprecation warning on every invocation.
+> In-process callers should use the `storage-app-mounts` trigger instead, or
+> the `storage` Go package directly.
+
+- Description: Returns a list of storage mounts for an app
+- Invoked by: external plugins (the core `storage:list` subcommand no longer uses it)
 - Arguments: `$APP $PHASE $FORMAT`
+
+### `storage-app-mounts`
+
+- Description: Returns the (entry, attachment) pairs an app has for the given phase, in JSON. Schedulers consume this to render volume mounts.
+- Invoked by: scheduler plugins during deploy
+- Arguments: `$APP $PHASE`
+- Output: a JSON array of objects shaped `{"entry": Entry, "attachment": Attachment}`
+
+### `storage-create`
+
+- Description: Provisions or updates the underlying volume for a k3s storage entry. Called when `storage:create` or `storage:set` runs against a k3s entry. Receives the JSON-encoded entry on stdin.
+- Invoked by: `dokku storage:create`, `dokku storage:set`
+- Arguments: `$ENTRY_NAME`
+- Stdin: JSON-encoded `Entry` payload
+
+### `storage-destroy`
+
+- Description: Releases the underlying volume for a k3s storage entry. Called when `storage:destroy` runs against a k3s entry. Receives the JSON-encoded entry on stdin.
+- Invoked by: `dokku storage:destroy`
+- Arguments: `$ENTRY_NAME`
+- Stdin: JSON-encoded `Entry` payload
+
+### `storage-status`
+
+- Description: Returns the current status of a storage entry's underlying volume. Used by `storage:wait` to poll the cluster. The handler should print one line: `Bound`, `Pending`, or `Lost` for k3s entries.
+- Invoked by: `dokku storage:wait`
+- Arguments: `$ENTRY_NAME`
+- Stdin: JSON-encoded `Entry` payload
+
+### `scheduler-storage-exec`
+
+- Description: Runs an interactive or non-interactive command against a storage entry. The storage plugin fires this with `<scheduler>` as the first arg; each scheduler plugin's handler matches against its own scheduler name and either handles or no-ops, mirroring `scheduler-deploy` / `scheduler-app-status`. Plugn forwards stdin/stdout/stderr to the handler subprocess so an interactive shell streams cleanly. The handler exits with the underlying tool's status code so `dokku storage:exec` propagates exit codes verbatim.
+- Invoked by: `dokku storage:exec`
+- Arguments: `$SCHEDULER $ENTRY_NAME $IMAGE [-- $cmd...]`
+- Flags: `--interactive` (stdin is open), `--tty` (stdin is a terminal), `--as-user <uid>` (override `entry.Chown`).
+
+### `scheduler-uses-host-cron`
+
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
+> between minor releases until the 1.0 release.
+
+- Description: Reports whether the scheduler writes `app.json` cron tasks to the host `dokku` user crontab. Schedulers that use the host crontab (`docker-local`) echo `true`; schedulers that manage their own cron backend (`k3s`, which creates in-cluster CronJobs) echo `false`. The cron plugin reads this to decide which apps to include when regenerating the host crontab; a scheduler that does not implement the trigger is treated as `false`.
+- Invoked by: `cron`
+- Arguments: `$DOKKU_SCHEDULER`
 - Example:
 
 ```shell
 #!/usr/bin/env bash
 
 set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
-APP="$1"
+DOKKU_SCHEDULER="$1";
 
-# TODO
+if [[ "$DOKKU_SCHEDULER" != "custom-scheduler" ]]; then
+  return
+fi
+
+echo "true"
 ```
 
 ### `traefik-template-source`

docs/development/release-process.md

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

docs/development/testing.md

@@ -13,7 +13,7 @@ All pull requests have tests run against them on [GitHub Actions](https://github
 
 If you wish to skip tests for a particular commit, e.g. documentation changes, you may add the `[ci skip]` designator to your commit message. Commits that _should_ be tested but have the above designator will not be merged.
 
-While we do provide official packages for a variety of platforms, as our test suite currently runs on Ubuntu Noble 24.04, we only provide official installation support for that platform and the supported LTS releases of Ubuntu (currently 20.04, 22.04, and 24.04).
+While we do provide official packages for a variety of platforms, as our test suite currently runs on Ubuntu Noble 24.04, we only provide official installation support for that platform and the supported LTS releases of Ubuntu (currently 22.04, and 24.04).
 
 ## Local Test Execution
 

docs/getting-started/install/docker.md

@@ -3,7 +3,7 @@
 Pull the dokku/dokku image:
 
 ```shell
-docker pull dokku/dokku:0.35.16
+docker pull dokku/dokku:0.38.27
 ```
 
 Next, run the image.
@@ -19,7 +19,7 @@ docker container run -d \
   --publish 8443:443 \
   --volume /var/lib/dokku:/mnt/dokku \
   --volume /var/run/docker.sock:/var/run/docker.sock \
-  dokku/dokku:0.35.16
+  dokku/dokku:0.38.27
 ```
 
 Alternatively, you can use `docker-compose.yml`:
@@ -27,7 +27,7 @@ Alternatively, you can use `docker-compose.yml`:
 ```yaml
 services:
   dokku:
-    image: dokku/dokku:0.35.16
+    image: dokku/dokku:0.38.27
     container_name: dokku
     network_mode: bridge
     ports:
@@ -44,7 +44,38 @@ services:
     restart: unless-stopped
 ```
 
-The above command will start a new docker container that is ready when a message similar to `Runit started as PID 12345` appears.
+## Container readiness
+
+The image ships with a Docker `HEALTHCHECK` that flips from `starting` to `healthy` once first-boot bootstrap is complete (skel restored, `plugin-list` plugins installed, core install triggers fired), nginx and sshd are accepting connections, and `dokku ps:restore` has finished. Until those conditions hold, the container is considered unhealthy and dependent services should not yet send traffic.
+
+To check the current state from the host:
+
+```shell
+docker inspect --format='{{.State.Health.Status}}' dokku
+```
+
+Internally, the check is backed by a loopback-only HTTP endpoint:
+
+```shell
+docker exec dokku curl -fsS http://127.0.0.1:18080/_dokku/health
+```
+
+The endpoint binds to `127.0.0.1:18080` inside the container by design - it is not published to the host and does not interfere with user app vhosts on ports 80/443.
+
+Compose dependents can gate on the healthcheck via `depends_on` with `condition: service_healthy`:
+
+```yaml
+services:
+  dokku:
+    image: dokku/dokku:0.38.27
+    # ...
+  bootstrap:
+    image: alpine:3.20
+    command: ["echo", "dokku is ready"]
+    depends_on:
+      dokku:
+        condition: service_healthy
+```
 
 Dokku is run in the following configuration:
 
@@ -80,12 +111,12 @@ redis: https://github.com/dokku/dokku-redis.git
 
 ### Prior to Dokku start
 
-The alternative is to build a custom docker image via a custom Dockerfile. This Dockerfile can run any `plugin:install` command. Note that the version installed at that time will be the one that persists. Below is an example Dockerfile showing this method.
+The alternative is to build a custom docker image via a custom Dockerfile. This Dockerfile can run any `plugin:install` command, though the `install` trigger must be skipped via the `--skip-install-trigger`. The version installed at that time will be the one that persists. Below is an example Dockerfile showing this method.
 
 ```Dockerfile
-FROM dokku/dokku:0.35.16
-RUN dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres
-RUN dokku plugin:install https://github.com/dokku/dokku-redis.git redis
+FROM dokku/dokku:0.38.27
+RUN dokku plugin:install https://github.com/dokku/dokku-postgres.git --skip-install-trigger
+RUN dokku plugin:install https://github.com/dokku/dokku-redis.git --skip-install-trigger
 ```
 
 ## SSH Key Management

docs/getting-started/install/vagrant.md

@@ -21,10 +21,10 @@
     # - `DOKKU_IP`
     # - `FORWARDED_PORT`.
     cd path/to/dokku
-    
+
     # for most users
     vagrant up
-    
+
     # windows users must instead use the following in an elevated command prompt
     vagrant up dokku-windows
     ```
@@ -42,7 +42,7 @@
 
     ```shell
     # usually your key is already available under the current user's `~/.ssh/authorized_keys` file
-    cat ~/.ssh/authorized_keys | dokku ssh-keys:add admin
+    cat ~/.ssh/authorized_keys | sudo dokku ssh-keys:add admin
 
     # you can use any domain you already have access to
     dokku domains:set-global dokku.me

docs/getting-started/installation/index.md

@@ -8,17 +8,11 @@ Dokku is an extensible, open source Platform as a Service that runs on a single
 
 To start using Dokku, you'll need a system that meets the following minimum requirements:
 
-- A fresh installation of any of the following operating systems:
-    - [Ubuntu 20.04/22.04/24.04](https://www.ubuntu.com/download)
-    - [Debian 11+ x64](https://www.debian.org/distrib/)
-- A server with one of the following architectures
-    - AMD64 (alternatively known as `x86_64`), commonly used for Intel cloud servers
-    - ARMV8 (alternatively known as `arm64`), commonly used for Raspberry PI and AWS Graviton
-
-To avoid memory pressure during builds or runtime of your applications, we suggest the following:
-
-- At least 1 GB of system memory
-    - If your system has less than 1GB of memory, you can use [this workaround](/docs/getting-started/advanced-installation.md#vms-with-less-than-1-gb-of-memory).
+- Operating Systems: [Ubuntu 22.04/24.04](https://www.ubuntu.com/download) or [Debian 11+ x64](https://www.debian.org/distrib/)
+- Supported Architectures: `AMD64` (`x86_64`) and `arm64` (`armv8`)
+- Minimum Memory:
+    - Docker Scheduler: 1GB of system memory, or [add swap memory](/docs/getting-started/advanced-installation.md#vms-with-less-than-1-gb-of-memory)
+    - K3s Scheduler: 2GB of system memory on every node in the cluster
 
 Finally, we recommend attaching at least one domain name to your server. This is not required, but using a domain name will make app access easier. When connecting a domain, either a single domain or a wildcard may be associated to the server's IP.
 
@@ -37,8 +31,8 @@ To install the latest stable version of Dokku, you can run the following shell c
 
 ```shell
 # for debian systems, installs Dokku via apt-get
-wget -NP . https://dokku.com/install/v0.35.16/bootstrap.sh
-sudo DOKKU_TAG=v0.35.16 bash bootstrap.sh
+wget -NP . https://dokku.com/install/v0.38.27/bootstrap.sh
+sudo DOKKU_TAG=v0.38.27 bash bootstrap.sh
 ```
 
 The installation process takes about 5-10 minutes, depending upon internet connection speed.
@@ -49,7 +43,7 @@ Once the installation is complete, you should configure an ssh key and set your
 
 ```shell
 # usually your key is already available under the current user's `~/.ssh/authorized_keys` file
-cat ~/.ssh/authorized_keys | dokku ssh-keys:add admin
+cat ~/.ssh/authorized_keys | sudo dokku ssh-keys:add admin
 
 # you can use any domain you already have access to
 # this domain should have an A record or CNAME pointing at your server's IP

docs/getting-started/upgrading/index.md

@@ -18,6 +18,9 @@ Docker releases updates periodically to their engine. We recommend reading their
 
 Before upgrading, check the migration guides to get comfortable with new features and prepare your deployment to be upgraded.
 
+- [Upgrading to 0.38](/docs/appendices/0.38.0-migration-guide.md)
+- [Upgrading to 0.37](/docs/appendices/0.37.0-migration-guide.md)
+- [Upgrading to 0.36](/docs/appendices/0.36.0-migration-guide.md)
 - [Upgrading to 0.35](/docs/appendices/0.35.0-migration-guide.md)
 - [Upgrading to 0.34](/docs/appendices/0.34.0-migration-guide.md)
 - [Upgrading to 0.33](/docs/appendices/0.33.0-migration-guide.md)
@@ -81,9 +84,6 @@ Please read the migration guides for each version in between your currently inst
 
 #### Upgrading using `dokku-update`
 
-> [!WARNING]
-> The `dokku-update` package currently does not support upgrading to a specific version of Dokku. If this is required by a particular migration guide, use the `apt` method for upgrading.
-
 We provide a helpful binary called `dokku-update`. This is a recommended package that:
 
 - Can be installed separately, so upgrading Dokku will not affect the running of this package.
@@ -150,4 +150,3 @@ new buildpacks that were released:
 ```shell
 dokku ps:rebuild --all
 ```
-

docs/home.html

@@ -10,26 +10,26 @@
     <meta name="author" content="">
     <title>Dokku - The smallest PaaS implementation you've ever seen</title>
 
-    <link rel="apple-touch-icon" sizes="57x57" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/apple-touch-icon-57x57.png">
-    <link rel="apple-touch-icon" sizes="60x60" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/apple-touch-icon-60x60.png">
-    <link rel="apple-touch-icon" sizes="72x72" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/apple-touch-icon-72x72.png">
-    <link rel="apple-touch-icon" sizes="76x76" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/apple-touch-icon-76x76.png">
-    <link rel="apple-touch-icon" sizes="114x114" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/apple-touch-icon-114x114.png">
-    <link rel="apple-touch-icon" sizes="120x120" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/apple-touch-icon-120x120.png">
-    <link rel="apple-touch-icon" sizes="144x144" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/apple-touch-icon-144x144.png">
-    <link rel="apple-touch-icon" sizes="152x152" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/apple-touch-icon-152x152.png">
-    <link rel="apple-touch-icon" sizes="180x180" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/apple-touch-icon-180x180.png">
-    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/favicon-32x32.png" sizes="32x32">
-    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/android-chrome-192x192.png" sizes="192x192">
-    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/favicon-96x96.png" sizes="96x96">
-    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/favicon-16x16.png" sizes="16x16">
-    <link rel="manifest" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/manifest.json">
-    <link rel="shortcut icon" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/favicon.ico">
+    <link rel="apple-touch-icon" sizes="57x57" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/apple-touch-icon-57x57.png">
+    <link rel="apple-touch-icon" sizes="60x60" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/apple-touch-icon-60x60.png">
+    <link rel="apple-touch-icon" sizes="72x72" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/apple-touch-icon-72x72.png">
+    <link rel="apple-touch-icon" sizes="76x76" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/apple-touch-icon-76x76.png">
+    <link rel="apple-touch-icon" sizes="114x114" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/apple-touch-icon-114x114.png">
+    <link rel="apple-touch-icon" sizes="120x120" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/apple-touch-icon-120x120.png">
+    <link rel="apple-touch-icon" sizes="144x144" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/apple-touch-icon-144x144.png">
+    <link rel="apple-touch-icon" sizes="152x152" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/apple-touch-icon-152x152.png">
+    <link rel="apple-touch-icon" sizes="180x180" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/apple-touch-icon-180x180.png">
+    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/favicon-32x32.png" sizes="32x32">
+    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/android-chrome-192x192.png" sizes="192x192">
+    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/favicon-96x96.png" sizes="96x96">
+    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/favicon-16x16.png" sizes="16x16">
+    <link rel="manifest" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/manifest.json">
+    <link rel="shortcut icon" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/favicon.ico">
     <meta name="apple-mobile-web-app-title" content="Dokku">
     <meta name="application-name" content="Dokku">
     <meta name="msapplication-TileColor" content="#da532c">
-    <meta name="msapplication-TileImage" content="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/mstile-144x144.png">
-    <meta name="msapplication-config" content="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/favicons/browserconfig.xml">
+    <meta name="msapplication-TileImage" content="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/mstile-144x144.png">
+    <meta name="msapplication-config" content="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/favicons/browserconfig.xml">
     <meta name="theme-color" content="#ffffff">
 
     <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-0evHe/X+R7YkIZDRvuzKMRqM+OrBnVFBL6DOitfPri4tjfHxaWutUpFmBp4vmVor" crossorigin="anonymous">
@@ -38,7 +38,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Lato:wght@400;700;900&display=swap" rel="stylesheet">
-    <link href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.35.16/docs/assets/style.css" rel="stylesheet">
+    <link href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.38.27/docs/assets/style.css" rel="stylesheet">
     <!-- <link href="./assets/style.css" rel="stylesheet"> -->
 </head>
 
@@ -98,7 +98,7 @@
         <main class="container px-4 px-lg-5">
             <div class="row">
                 <div class="col-lg-7">
-                    <a class="badge-link" href="https://github.com/dokku/dokku/releases"><span class="badge py-2 d-flex fit-content"><div class="circle align-self-center me-2"></div>Latest release <span id="releaseVersion" class="ms-1">v0.35.16</span></span></a>
+                    <a class="badge-link" href="https://github.com/dokku/dokku/releases"><span class="badge py-2 d-flex fit-content"><div class="circle align-self-center me-2"></div>Latest release <span id="releaseVersion" class="ms-1">v0.38.27</span></span></a>
                     <h1 class="text-white hero-heading mt-5">An open source PAAS alternative to Heroku.</h1>
                     <h4 class="text-white mt-5">Dokku helps you build and manage the lifecycle of applications from building to scaling.</h4>
                     <div class="d-flex mt-5">
@@ -125,7 +125,7 @@
                             </p>
                             <p class="line">
                                 <span class="prompt">$</span>
-                                <span class="command">sudo DOKKU_TAG=v0.35.16 bash bootstrap.sh</span>
+                                <span class="command">sudo DOKKU_TAG=v0.38.27 bash bootstrap.sh</span>
                             </p>
                             <br>
 

docs/networking/network.md

@@ -8,7 +8,7 @@ network:create <network>                    # Creates an attachable docker netwo
 network:destroy <network>                   # Destroys a docker network
 network:exists <network>                    # Checks if a docker network exists
 network:info <network> [--format text|json] # Outputs information about a docker network
-network:list [--format text|json]           # Lists all docker networks
+network:list [--format text|json] [--dokku-managed] # Lists all docker networks
 network:report [<app>] [<flag>]             # Displays a network report for one or more apps
 network:rebuild <app>                       # Rebuilds network settings for an app
 network:rebuildall                          # Rebuild network settings for all apps
@@ -59,13 +59,26 @@ dokku network:list --format json
 
 ```
 [
-    {"CreatedAt":"2024-02-25T01:55:24.275184461Z","Driver":"bridge","ID":"d18df2d21433","Internal":false,"IPv6":false,"Labels":{},"Name":"bridge","Scope":"local"},
-    {"CreatedAt":"2024-02-25T01:55:24.275184461Z","Driver":"bridge","ID":"f50fa882e7de","Internal":false,"IPv6":false,"Labels":{},"Name":"test-network","Scope":"local"},
-    {"CreatedAt":"2024-02-25T01:55:24.275184461Z","Driver":"host","ID":"ab6a59291443","Internal":false,"IPv6":false,"Labels":{},"Name":"host","Scope":"local"},
-    {"CreatedAt":"2024-02-25T01:55:24.275184461Z","Driver":"null","ID":"e2506bc8b7d7","Internal":false,"IPv6":false,"Labels":{},"Name":"none","Scope":"local"}
+    {"CreatedAt":"2024-02-25T01:55:24.275184461Z","DokkuManaged":false,"Driver":"bridge","ID":"d18df2d21433","Internal":false,"IPv6":false,"Labels":{},"Name":"bridge","Scope":"local"},
+    {"CreatedAt":"2024-02-25T01:55:24.275184461Z","DokkuManaged":true,"Driver":"bridge","ID":"f50fa882e7de","Internal":false,"IPv6":false,"Labels":{"com.dokku.network-name":"test-network"},"Name":"test-network","Scope":"local"},
+    {"CreatedAt":"2024-02-25T01:55:24.275184461Z","DokkuManaged":false,"Driver":"host","ID":"ab6a59291443","Internal":false,"IPv6":false,"Labels":{},"Name":"host","Scope":"local"},
+    {"CreatedAt":"2024-02-25T01:55:24.275184461Z","DokkuManaged":false,"Driver":"null","ID":"e2506bc8b7d7","Internal":false,"IPv6":false,"Labels":{},"Name":"none","Scope":"local"}
 ]
 ```
 
+The `DokkuManaged` field is `true` for networks created by `network:create` and `false` for Docker built-in networks (such as `bridge`, `host`, and `none`) or networks created outside of Dokku (such as compose `*_default` networks). This can be used by automation to determine which networks Dokku is responsible for.
+
+The `network:list` command also takes a `--dokku-managed` flag, which restricts the output to only those networks created by Dokku. It can be combined with the `--format` flag:
+
+```shell
+dokku network:list --dokku-managed
+```
+
+```
+=====> Networks
+test-network
+```
+
 ### Creating a network
 
 > [!IMPORTANT]
@@ -142,10 +155,11 @@ dokku network:info bridge
 
 ```
 =====> bridge network information
-       ID:       d18df2d21433
-       Name:     bridge
-       Driver:   bridge
-       Scope:    local
+       ID:             d18df2d21433
+       Name:           bridge
+       Driver:         bridge
+       Scope:          local
+       Dokku managed:  false
 ```
 
 The `network:info` command also takes a `--format` flag, with the valid options including `text` (default) and `json`. The `json` output format can be used for automation purposes:
@@ -155,7 +169,7 @@ dokku network:info bridge --format json
 ```
 
 ```
-{"CreatedAt":"2024-02-25T01:55:24.275184461Z","Driver":"bridge","ID":"d18df2d21433","Internal":false,"IPv6":false,"Labels":{},"Name":"bridge","Scope":"local"}
+{"CreatedAt":"2024-02-25T01:55:24.275184461Z","DokkuManaged":false,"Driver":"bridge","ID":"d18df2d21433","Internal":false,"IPv6":false,"Labels":{},"Name":"bridge","Scope":"local"}
 ```
 
 ### Routing an app to a known ip:port combination
@@ -428,7 +442,7 @@ dokku network:report
 =====> node-js-app network information
        Network attach post create:
        Network attach post deploy:
-       Network bind all interfaces:   false
+       Network bind all interfaces:
        Network computed attach post create:
        Network computed attach post deploy:
        Network computed bind all interfaces:false
@@ -436,7 +450,7 @@ dokku network:report
        Network computed tld:
        Network global attach post create:
        Network global attach post deploy:
-       Network global bind all interfaces:false
+       Network global bind all interfaces:
        Network global initial network:
        Network global tld:
        Network initial network:
@@ -445,7 +459,7 @@ dokku network:report
 =====> python-sample network information
        Network attach post create:
        Network attach post deploy:
-       Network bind all interfaces:   false
+       Network bind all interfaces:
        Network computed attach post create:
        Network computed attach post deploy:
        Network computed bind all interfaces:false
@@ -453,7 +467,7 @@ dokku network:report
        Network computed tld:
        Network global attach post create:
        Network global attach post deploy:
-       Network global bind all interfaces:false
+       Network global bind all interfaces:
        Network global initial network:
        Network global tld:
        Network initial network:
@@ -462,7 +476,7 @@ dokku network:report
 =====> ruby-sample network information
        Network attach post create:
        Network attach post deploy:
-       Network bind all interfaces:   false
+       Network bind all interfaces:
        Network computed attach post create:
        Network computed attach post deploy:
        Network computed bind all interfaces:false
@@ -470,7 +484,7 @@ dokku network:report
        Network computed tld:
        Network global attach post create:
        Network global attach post deploy:
-       Network global bind all interfaces:false
+       Network global bind all interfaces:
        Network global initial network:
        Network global tld:
        Network initial network:
@@ -478,6 +492,8 @@ dokku network:report
        Network web listeners:
 ```
 
+The per-app and `global-` keys for each property hold the raw values and are empty when nothing has been set. The `computed-` keys hold the effective value, falling back to the global value (where one has been set) and then to the built-in default (`false` for `bind-all-interfaces`, empty otherwise).
+
 You can run the command for a specific app also.
 
 ```shell
@@ -488,7 +504,7 @@ dokku network:report node-js-app
 =====> node-js-app network information
        Network attach post create:
        Network attach post deploy:
-       Network bind all interfaces:   false
+       Network bind all interfaces:
        Network computed attach post create:
        Network computed attach post deploy:
        Network computed bind all interfaces:false
@@ -496,7 +512,7 @@ dokku network:report node-js-app
        Network computed tld:
        Network global attach post create:
        Network global attach post deploy:
-       Network global bind all interfaces:false
+       Network global bind all interfaces:
        Network global initial network:
        Network global tld:
        Network initial network:
@@ -509,3 +525,27 @@ You can pass flags which will output only the value of the specific information
 ```shell
 dokku network:report node-js-app --network-bind-all-interfaces
 ```
+
+## Properties
+
+### Settable properties
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `network:report`. The JSON keys emitted by `network:report --format json` are the same names with the leading `--network-` stripped (e.g. `attach-post-create`, `global-attach-post-create`, `computed-attach-post-create`). Legacy keys with the `network-` prefix (e.g. `network-attach-post-create`) 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 |
+|---|---|---|---|---|
+| `attach-post-create` | app + global | none | `--network-attach-post-create`, `--network-global-attach-post-create`, `--network-computed-attach-post-create` | Networks attached to a container immediately after creation, before the deploy phase |
+| `attach-post-deploy` | app + global | none | `--network-attach-post-deploy`, `--network-global-attach-post-deploy`, `--network-computed-attach-post-deploy` | Networks attached to a container after it passes healthchecks |
+| `bind-all-interfaces` | app + global | `false` | `--network-bind-all-interfaces`, `--network-global-bind-all-interfaces`, `--network-computed-bind-all-interfaces` | When `true`, binds containers to `0.0.0.0` instead of the default Docker network address |
+| `initial-network` | app + global | none | `--network-initial-network`, `--network-global-initial-network`, `--network-computed-initial-network` | Network attached at container creation time |
+| `static-web-listener` | app only | none | `--network-static-web-listener` | Static `host:port` override used in proxy templates when no container is running |
+| `tld` | app + global | none | `--network-tld`, `--network-global-tld`, `--network-computed-tld` | Top-level domain appended to auto-generated app vhosts |
+
+### Read-only flags
+
+The following flag surfaces in `network:report` but is not managed by `network:set` - it is derived from the running app state:
+
+| Flag | Description |
+|---|---|
+| `--network-web-listeners` | Current `web` process listeners (host:port) for the deployed app |

docs/networking/port-management.md

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

docs/networking/proxies/caddy.md

@@ -3,15 +3,15 @@
 > [!IMPORTANT]
 > New as of 0.28.0
 
-Dokku provides integration with the [Caddy](https://caddyserver.com/) proxy service by utilizing the Docker label-based integration implemented by Caddy.
+Dokku provides integration with the [Caddy](https://caddyserver.com/) proxy service by utilizing the Docker label-based integration implemented by [Caddy Docker Proxy](https://github.com/lucaslorentz/caddy-docker-proxy).
 
 ```
-caddy:report [<app>] [<flag>]            # Displays a caddy report for one or more apps
-caddy:logs [--num num] [--tail]          # Display caddy log output
-caddy:set <app> <property> (<value>)     # Set or clear an caddy property for an app
-caddy:show-config <app>                  # Display caddy compose config
-caddy:start                              # Starts the caddy server
-caddy:stop                               # Stops the caddy server
+caddy:report [<app>] [<flag>]                            # Displays a caddy report for one or more apps
+caddy:logs [--num num] [--tail]                          # Display caddy log output
+caddy:set [<app>|--global] <property> (<value>)          # Set or clear an caddy property for an app or globally
+caddy:show-config <app>                                  # Display caddy compose config
+caddy:start                                              # Starts the caddy server
+caddy:stop                                               # Stops the caddy server
 ```
 
 ## Requirements
@@ -39,7 +39,7 @@ The Caddy plugin has specific rules for routing requests:
 To use the Caddy plugin, use the `proxy:set` command for the app in question:
 
 ```shell
-dokku proxy:set node-js-app caddy
+dokku proxy:set node-js-app type caddy
 ```
 
 This will enable the docker label-based Caddy integration. All future deploys will inject the correct labels for Caddy to read and route requests to containers. Due to the docker label-based integration used by Caddy, a single deploy or rebuild will be required before requests will route successfully.
@@ -117,9 +117,57 @@ dokku caddy:set --global log-level DEBUG
 
 After modifying,  the Caddy container will need to be restarted.
 
+### Label Management
+
+The Caddy plugin allows you to add custom container labels to apps. These labels are injected into containers during deployment and can be used to configure Caddy behavior beyond what the plugin provides by default.
+
+Refer to the upstream [caddy-docker-proxy](https://github.com/lucaslorentz/caddy-docker-proxy) documentation for more information on what labels are available.
+
+#### Adding a label
+
+To add a custom container label to an app, use the `caddy:labels:add` command:
+
+```shell
+dokku caddy:labels:add node-js-app caddy.directive value
+```
+
+This will add the label `caddy.directive=value` to the app's containers. After adding a label, you will need to rebuild or redeploy the app for the label to be applied to running containers.
+
+```shell
+dokku ps:rebuild node-js-app
+```
+
+#### Removing a label
+
+To remove a custom container label from an app, use the `caddy:labels:remove` command:
+
+```shell
+dokku caddy:labels:remove node-js-app caddy.directive
+```
+
+This will remove the specified label from the app. After removing a label, you will need to rebuild or redeploy the app for the change to be applied to running containers.
+
+```shell
+dokku ps:rebuild node-js-app
+```
+
+#### Showing labels
+
+To view all custom container labels for an app, use the `caddy:labels:show` command:
+
+```shell
+dokku caddy:labels:show node-js-app
+```
+
+To view a specific label value, provide the label name:
+
+```shell
+dokku caddy:labels:show node-js-app caddy.directive
+```
+
 ### SSL Configuration
 
-The caddy plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
+The caddy plugin only supports automatic ssl certificates from its letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
 
 #### Enabling letsencrypt integration
 
@@ -143,12 +191,25 @@ After enabling, the Caddy container will need to be restarted and apps will need
 
 ### Using Caddy's Internal TLS server
 
-To switch to Caddy's internal TLS server for certificate provisioning, set the `tls-internal` property. This can only be set on a per-app basis.
+To switch to Caddy's internal TLS server for certificate provisioning, set the `tls-internal` property.
 
 ```shell
 dokku caddy:set node-js-app tls-internal true
 ```
 
+The default value may also be configured globally with the `--global` flag. Per-app values take precedence over the global value when set.
+
+```shell
+dokku caddy:set --global tls-internal true
+```
+
+Both the per-app and the global value may be unset by setting a blank value.
+
+```shell
+dokku caddy:set node-js-app tls-internal
+dokku caddy:set --global tls-internal
+```
+
 ## Displaying Caddy reports for an app
 
 You can get a report about the app's Caddy config using the `caddy:report` command:
@@ -159,28 +220,23 @@ dokku caddy:report
 
 ```
 =====> node-js-app caddy information
-       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7
-       Caddy letsencrypt email:
-       Caddy letsencrypt server:
-       Caddy log level:               ERROR
-       Caddy polling interval:        5s
-       Caddy tls internal:            false
-=====> python-app caddy information
-       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7
-       Caddy letsencrypt email:
-       Caddy letsencrypt server:
-       Caddy log level:               ERROR
-       Caddy polling interval:        5s
-       Caddy tls internal:            false
-=====> ruby-app caddy information
-       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7
-       Caddy letsencrypt email:
-       Caddy letsencrypt server:
-       Caddy log level:               ERROR
-       Caddy polling interval:        5s
-       Caddy tls internal:            false
+       Caddy computed image:             lucaslorentz/caddy-docker-proxy:2.7
+       Caddy computed letsencrypt email:
+       Caddy computed letsencrypt server: https://acme-v02.api.letsencrypt.org/directory
+       Caddy computed log level:         ERROR
+       Caddy computed polling interval:  5s
+       Caddy computed tls internal:      false
+       Caddy global image:
+       Caddy global letsencrypt email:
+       Caddy global letsencrypt server:
+       Caddy global log level:
+       Caddy global polling interval:
+       Caddy global tls internal:
+       Caddy tls internal:
 ```
 
+The `global-<prop>` keys hold the raw global value and are empty when nothing has been set globally. The `computed-<prop>` keys hold 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. The bare `tls-internal` key holds the raw per-app value.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -189,16 +245,44 @@ dokku caddy:report node-js-app
 
 ```
 =====> node-js-app caddy information
-       Caddy image:                   lucaslorentz/caddy-docker-proxy:2.7
-       Caddy letsencrypt email:
-       Caddy letsencrypt server:
-       Caddy log level:               ERROR
-       Caddy polling interval:        5s
-       Caddy tls internal:            false
+       Caddy computed image:             lucaslorentz/caddy-docker-proxy:2.7
+       Caddy computed letsencrypt email:
+       Caddy computed letsencrypt server: https://acme-v02.api.letsencrypt.org/directory
+       Caddy computed log level:         ERROR
+       Caddy computed polling interval:  5s
+       Caddy computed tls internal:      false
+       Caddy global image:
+       Caddy global letsencrypt email:
+       Caddy global letsencrypt server:
+       Caddy global log level:
+       Caddy global polling interval:
+       Caddy global tls internal:
+       Caddy tls internal:
 ```
 
 You can pass flags which will output only the value of the specific information you want. For example:
 
 ```shell
-dokku caddy:report node-js-app --caddy-image
+dokku caddy:report node-js-app --caddy-computed-image
 ```
+
+## Properties
+
+### Settable properties
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `image` | global only | _parsed from `plugins/caddy-vhosts/Dockerfile`_ | `--caddy-global-image`, `--caddy-computed-image` | Docker image used to run the Caddy container |
+| `letsencrypt-email` | global only | none | `--caddy-global-letsencrypt-email`, `--caddy-computed-letsencrypt-email` | Contact email enabling letsencrypt; empty disables https issuance |
+| `letsencrypt-server` | global only | `https://acme-v02.api.letsencrypt.org/directory` | `--caddy-global-letsencrypt-server`, `--caddy-computed-letsencrypt-server` | ACME directory used when requesting certificates |
+| `log-level` | global only | `ERROR` | `--caddy-global-log-level`, `--caddy-computed-log-level` | Caddy log level |
+| `polling-interval` | global only | `5s` | `--caddy-global-polling-interval`, `--caddy-computed-polling-interval` | Frequency at which Caddy polls the Docker API for label changes |
+| `tls-internal` | app + global | `false` | `--caddy-tls-internal`, `--caddy-global-tls-internal`, `--caddy-computed-tls-internal` | When `true`, uses Caddy's built-in self-signed TLS instead of letsencrypt |
+
+### Internal properties
+
+The following properties are not managed by `caddy:set` but are recorded internally by the plugin:
+
+| Property | Description | Source |
+|---|---|---|
+| `proxy-status` | `started`/`stopped` state of the caddy compose project | `cmd-caddy-start`/`cmd-caddy-stop` in `plugins/caddy-vhosts/command-functions` |

docs/networking/proxies/haproxy.md

@@ -35,7 +35,7 @@ The Haproxy plugin has specific rules for routing requests:
 To use the Haproxy plugin, use the `proxy:set` command for the app in question:
 
 ```shell
-dokku proxy:set node-js-app haproxy
+dokku proxy:set node-js-app type haproxy
 ```
 
 This will enable the docker label-based Haproxy integration. All future deploys will inject the correct labels for Haproxy to read and route requests to containers. Due to the docker label-based integration used by Haproxy, a single deploy or rebuild will be required before requests will route successfully.
@@ -113,6 +113,64 @@ dokku haproxy:set --global log-level DEBUG
 
 After modifying,  the Haproxy container will need to be restarted.
 
+### Changing the Haproxy refresh interval
+
+Haproxy polls the Docker API for label changes every `10` seconds by default. The interval may be changed by setting the `refresh-conf` property with the `--global` flag:
+
+```shell
+dokku haproxy:set --global refresh-conf 5
+```
+
+The `refresh-conf` property is global-only and cannot be set on a per-app basis. Setting an empty value will reset it to the default. After modifying, the Haproxy container will need to be restarted.
+
+### Label Management
+
+The Haproxy plugin allows you to add custom container labels to apps. These labels are injected into containers during deployment and can be used to configure Haproxy behavior beyond what the plugin provides by default.
+
+Refer to the upstream [EasyHaproxy](https://github.com/byjg/docker-easy-haproxy) documentation for more information on what labels are available.
+
+#### Adding a label
+
+To add a custom container label to an app, use the `haproxy:labels:add` command:
+
+```shell
+dokku haproxy:labels:add node-js-app haproxy.directive value
+```
+
+This will add the label `haproxy.directive=value` to the app's containers. After adding a label, you will need to rebuild or redeploy the app for the label to be applied to running containers.
+
+```shell
+dokku ps:rebuild node-js-app
+```
+
+#### Removing a label
+
+To remove a custom container label from an app, use the `haproxy:labels:remove` command:
+
+```shell
+dokku haproxy:labels:remove node-js-app haproxy.directive
+```
+
+This will remove the specified label from the app. After removing a label, you will need to rebuild or redeploy the app for the change to be applied to running containers.
+
+```shell
+dokku ps:rebuild node-js-app
+```
+
+#### Showing labels
+
+To view all custom container labels for an app, use the `haproxy:labels:show` command:
+
+```shell
+dokku haproxy:labels:show node-js-app
+```
+
+To view a specific label value, provide the label name:
+
+```shell
+dokku haproxy:labels:show node-js-app haproxy.directive
+```
+
 ### SSL Configuration
 
 The haproxy plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
@@ -147,13 +205,20 @@ dokku haproxy:report
 
 ```
 =====> node-js-app haproxy information
-       Haproxy image:                   byjg/easy-haproxy:4.0.0
-=====> python-app haproxy information
-       Haproxy image:                   byjg/easy-haproxy:4.0.0
-=====> ruby-app haproxy information
-       Haproxy image:                   byjg/easy-haproxy:4.0.0
+       Haproxy computed image:           byjg/easy-haproxy:4.0.0
+       Haproxy computed letsencrypt email:
+       Haproxy computed letsencrypt server: https://acme-v02.api.letsencrypt.org/directory
+       Haproxy computed log level:       ERROR
+       Haproxy computed refresh conf:    10
+       Haproxy global image:
+       Haproxy global letsencrypt email:
+       Haproxy global letsencrypt server:
+       Haproxy global log level:
+       Haproxy global refresh conf:
 ```
 
+The `global-<prop>` keys hold the raw global value and are empty when nothing has been set globally. The `computed-<prop>` keys hold the effective value used at deploy time, falling back to the built-in default when the global value is empty.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -162,11 +227,42 @@ dokku haproxy:report node-js-app
 
 ```
 =====> node-js-app haproxy information
-       Haproxy image:                   byjg/easy-haproxy:4.0.0
+       Haproxy computed image:           byjg/easy-haproxy:4.0.0
+       Haproxy computed letsencrypt email:
+       Haproxy computed letsencrypt server: https://acme-v02.api.letsencrypt.org/directory
+       Haproxy computed log level:       ERROR
+       Haproxy computed refresh conf:    10
+       Haproxy global image:
+       Haproxy global letsencrypt email:
+       Haproxy global letsencrypt server:
+       Haproxy global log level:
+       Haproxy global refresh conf:
 ```
 
 You can pass flags which will output only the value of the specific information you want. For example:
 
 ```shell
-dokku haproxy:report node-js-app --haproxy-image
+dokku haproxy:report node-js-app --haproxy-computed-image
 ```
+
+## Properties
+
+### Settable properties
+
+All haproxy properties are global only. Set with `haproxy:set --global <property> <value>`.
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `image` | global only | _parsed from `plugins/haproxy-vhosts/Dockerfile`_ | `--haproxy-global-image`, `--haproxy-computed-image` | Docker image used to run the Haproxy container |
+| `letsencrypt-email` | global only | none | `--haproxy-global-letsencrypt-email`, `--haproxy-computed-letsencrypt-email` | Contact email enabling letsencrypt; empty disables https issuance |
+| `letsencrypt-server` | global only | `https://acme-v02.api.letsencrypt.org/directory` | `--haproxy-global-letsencrypt-server`, `--haproxy-computed-letsencrypt-server` | ACME directory used when requesting certificates |
+| `log-level` | global only | `ERROR` | `--haproxy-global-log-level`, `--haproxy-computed-log-level` | Haproxy log level |
+| `refresh-conf` | global only | `10` | `--haproxy-global-refresh-conf`, `--haproxy-computed-refresh-conf` | Seconds between Haproxy polls of the Docker API for label changes |
+
+### Internal properties
+
+The following properties are not managed by `haproxy:set` but are recorded internally by the plugin:
+
+| Property | Description | Source |
+|---|---|---|
+| `proxy-status` | `started`/`stopped` state of the haproxy compose project | `cmd-haproxy-start`/`cmd-haproxy-stop` in `plugins/haproxy-vhosts/command-functions` |

docs/networking/proxies/nginx.md

@@ -5,7 +5,8 @@ Dokku uses nginx as its server for routing requests to specific applications. By
 ```
 nginx:access-logs <app> [-t]             # Show the nginx access logs for an application (-t follows)
 nginx:error-logs <app> [-t]              # Show the nginx error logs for an application (-t follows)
-nginx:report [<app>] [<flag>]            # Displays a nginx report for one or more apps
+nginx:reload                             # Reloads the nginx server config
+nginx:report [<app>] [<flag>|--format json] # Displays a nginx report for one or more apps
 nginx:set <app> <property> (<value>)     # Set or clear an nginx property for an app
 nginx:show-config <app>                  # Display app nginx config
 nginx:start                              # Starts the nginx server
@@ -27,6 +28,21 @@ Nginx will proxy the requests in a [round-robin balancing fashion](http://nginx.
 > [!NOTE]
 > Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers.
 
+### Nginx Configuration for Undeployed Apps
+
+> [!IMPORTANT]
+> New as of 0.38.0
+
+When an app is created but not yet deployed, has no `web` process type, or has no running web processes, Dokku generates a minimal nginx configuration that returns `502 Bad Gateway` responses. This ensures that:
+
+- The app's domain resolves and returns a non-200 status code, allowing monitoring tools to detect the issue.
+- SSL certificate provisioning tools such as letsencrypt can function, as an nginx server is listening on the domain.
+- The `nginx.conf.d/` include directory is available for plugin customization.
+
+The 502 error page includes auto-retry JavaScript that will automatically reload the page when the application becomes available.
+
+Once the app is deployed with running `web` processes, the placeholder configuration is automatically replaced with the full proxy configuration.
+
 ### Starting nginx
 
 > [!IMPORTANT]
@@ -49,6 +65,19 @@ The nginx server can be stopped via `nginx:stop`.
 dokku nginx:stop
 ```
 
+### Reloading nginx
+
+> [!IMPORTANT]
+> New as of 0.38.0
+
+The nginx server can be reloaded via `nginx:reload`. This validates the current nginx configuration and, if valid, signals nginx to reload without restarting the running process. This is the preferred command after editing files in `/etc/nginx/conf.d/` directly.
+
+```shell
+dokku nginx:reload
+```
+
+If the configuration is invalid, the command exits non-zero and prints the validation error without reloading.
+
 ### Checking access logs
 
 > [!NOTE]
@@ -90,7 +119,11 @@ dokku nginx:show-config node-js-app
 
 ### Validating nginx configs
 
-It may be desired to validate an nginx config outside of the deployment process. To do so, run the `nginx:validate-config` command. With no arguments, this will validate all app nginx configs, one at a time. A minimal wrapper nginx config is generated for each app's nginx config, upon which `nginx -t` will be run.
+App-supplied `nginx.conf.sigil` files are pre-validated automatically at the start of every deploy, immediately after the template is extracted from the source tree and before the build phase runs. The template is rendered with sigil and run through `nginx -t` against a minimal wrapper config; if validation fails, the deploy is aborted before any build work begins. To bypass this behavior, set `disable-custom-config` to `true` (see "Disabling custom nginx config" below).
+
+The wrapper config used for validation does not include the top-level `load_module` directives from the global nginx config, so a `nginx.conf.sigil` that relies on a directive from a dynamically loaded module will fail this validation even when `nginx -t` passes against the real server config. See [Custom nginx modules](/docs/appendices/file-formats/nginx-conf-sigil.md#custom-nginx-modules) for how to supply a custom validation wrapper via the `nginx-app-template-source` trigger's `validate-config` template type.
+
+It may also be desired to validate an nginx config outside of the deployment process. To do so, run the `nginx:validate-config` command. With no arguments, this will validate all app nginx configs, one at a time. A minimal wrapper nginx config is generated for each app's nginx config, upon which `nginx -t` will be run.
 
 ```shell
 dokku nginx:validate-config
@@ -113,6 +146,34 @@ The `--clean` flag may also be specified for a given app:
 dokku nginx:validate-config node-js-app --clean
 ```
 
+### Displaying nginx reports for an app
+
+You can get a report about the app's nginx configuration using the `nginx:report` command:
+
+```shell
+dokku nginx:report
+```
+
+You can run the command for a specific app also.
+
+```shell
+dokku nginx:report node-js-app
+```
+
+You can pass flags which will output only the value of the specific information you want. For example:
+
+```shell
+dokku nginx:report node-js-app --nginx-bind-address-ipv4
+```
+
+The `nginx:report` command also takes a `--format` flag, with the valid options including `stdout` (default) and `json`. The `json` output format can be used for automation purposes:
+
+```shell
+dokku nginx:report node-js-app --format json
+```
+
+The `--format` flag cannot be combined with an info flag.
+
 ### Custom Error Pages
 
 By default, Dokku provides custom error pages for the following three categories of errors:
@@ -125,52 +186,107 @@ These are provided as an alternative to the generic Nginx error page, are shared
 
 ### Default site
 
-By default, Dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. This means that accessing the dokku server via its IP address or a bogus domain name may return a seemingly random website.
+> [!IMPORTANT]
+> New as of 0.38.0
 
-> [!WARNING]
-> Some versions of Nginx may create a default site when installed. This site is simply a static page which says "Welcome to Nginx", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands:
->
-> ```
-> rm /etc/nginx/sites-enabled/default
-> dokku nginx:stop
-> dokku nginx:start
-> ```
+On fresh apt installs, Dokku ships a catch-all default site at `/etc/nginx/conf.d/00-default-vhost.conf` that rejects requests whose Host header (or TLS SNI) does not match any deployed app. The catch-all uses [`ssl_reject_handshake on`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_reject_handshake) for HTTPS and [`return 444`](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return) for HTTP. Both close the connection without sending a response.
 
-If services should only be accessed via their domain name, you may want to disable the default site by adding the following configuration to the global nginx configuration.
-
-Create the file at `/etc/nginx/conf.d/00-default-vhost.conf`:
+The shipped file looks like:
 
 ```nginx
 server {
-    listen 80 default_server;
-    listen [::]:80 default_server;
-
-    # If services hosted by dokku are available via HTTPS, it is recommended
-    # to also uncomment the following section.
-    #
-    # Please note that in order to let this work, you need an SSL certificate. However
-    # it does not need to be valid. Users of Debian-based distributions can install the
-    # `ssl-cert` package with `sudo apt install ssl-cert` to automatically generate
-    # a self-signed certificate that is stored at `/etc/ssl/certs/ssl-cert-snakeoil.pem`.
-    #
-    #listen 443 ssl;
-    #listen [::]:443 ssl;
-    #ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
-    #ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
+    listen      80 default_server;
+    listen      [::]:80 default_server;
+    listen      443 ssl default_server;
+    listen      [::]:443 ssl default_server;
 
     server_name _;
-    access_log off;
+    access_log  off;
+
+    ssl_reject_handshake on;
     return 444;
 }
 ```
 
-Make sure to reload nginx after creating this file by running `systemctl reload nginx.service`.
+The `00-` prefix forces nginx to load this file before `/etc/nginx/conf.d/dokku.conf`, so its `default_server` markers establish the default for each port before any per-app server blocks are loaded.
 
-This will catch all unknown HOST header values and close the connection without responding. You can replace the `return 444;` with `return 410;` which will cause nginx to respond with an error page.
+On systems running nginx older than 1.19.4 (e.g., Debian Bullseye, which ships nginx 1.18.0), `ssl_reject_handshake` is not available. The postinst detects this and installs an HTTP-only variant instead:
 
-The configuration file must be loaded before `/etc/nginx/conf.d/dokku.conf`, so it can not be arranged as a vhost in `/etc/nginx/sites-enabled` that is only processed afterwards.
+```nginx
+server {
+    listen      80 default_server;
+    listen      [::]:80 default_server;
 
-Alternatively, you may push an app to your Dokku host with a name like "00-default". As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
+    server_name _;
+    access_log  off;
+
+    return 444;
+}
+```
+
+On these systems, HTTPS requests to unknown hosts are not rejected by the catch-all - nginx falls through to the lexicographically first port-443 server block and presents that block's certificate, the same behavior as before 0.38.0.
+
+#### TLS handshake behavior
+
+The catch-all does not affect TLS handshakes for legitimate apps. nginx selects the matching server block via SNI before completing the handshake; only requests that have no matching app fall through to the catch-all.
+
+| Request | Result |
+| --- | --- |
+| HTTPS to a configured app's hostname (with matching SNI) and the app has a cert | Handshake completes with the app's cert. Catch-all not consulted. |
+| HTTPS to a configured app's hostname when the app has no cert configured | Handshake rejected by the catch-all on nginx 1.19.4+. On older nginx, falls through to the lexicographically first port-443 server block and presents its cert, producing a cert-mismatch error. |
+| HTTPS to the server's IP with no SNI, or with an SNI matching no app | Handshake rejected on nginx 1.19.4+. On older nginx, falls through to the first port-443 server block. |
+| HTTP to a configured app's hostname | Routed normally to that app. Catch-all not consulted. |
+| HTTP to a hostname matching no app | Catch-all `return 444`. |
+
+#### Conflicting upstream nginx default vhost
+
+A fresh nginx install ships its own default vhost that also claims port 80 with `default_server`, which would cause `nginx -t` to fail with `a duplicate default server for 0.0.0.0:80` once the dokku catch-all is in place. To avoid this, the dokku postinst renames any of the following files in place to `${path}.dokku-disabled` instead of deleting them, preserving any local customizations:
+
+- `/etc/nginx/sites-enabled/default`
+- `/etc/nginx/sites-available/default`
+- `/etc/nginx/conf.d/default.conf`
+
+To recover an original file, inspect the `.dokku-disabled` sibling.
+
+#### Disabling the catch-all on first install
+
+Select "No" at the `dokku/install_default_site` debconf prompt, or pre-seed the answer before installing:
+
+```shell
+echo 'dokku dokku/install_default_site boolean false' | debconf-set-selections
+```
+
+#### Customizing or removing the catch-all after install
+
+To customize the reject behavior, edit `/etc/nginx/conf.d/00-default-vhost.conf` and reload:
+
+```shell
+dokku nginx:reload
+```
+
+For example, replace `return 444;` with `return 410;` to respond with an HTTP 410 Gone error page instead of dropping the connection.
+
+To disable the catch-all without uninstalling dokku:
+
+```shell
+mv /etc/nginx/conf.d/00-default-vhost.conf{,.disabled}
+dokku nginx:reload
+```
+
+#### Installing the catch-all on upgraded or non-apt installs
+
+Existing dokku installs upgraded from earlier versions do not get the catch-all installed automatically; the upgrade leaves their nginx configuration untouched. To install it manually, copy the shipped template into place and reload nginx:
+
+```shell
+cp /var/lib/dokku/core-plugins/available/nginx-vhosts/templates/default-site.conf /etc/nginx/conf.d/00-default-vhost.conf
+dokku nginx:reload
+```
+
+If the upstream nginx default vhost is also active, disable it first (e.g. `mv /etc/nginx/sites-enabled/default{,.disabled}`) to avoid a duplicate-default-server error.
+
+#### App-name based alternative
+
+As an alternative to the catch-all file, you may push an app to your Dokku host with a name like `00-default`. As long as it lists first in `ls /home/dokku/*/nginx.conf | head`, it will be used as the default nginx vhost.
 
 ### Customizing the nginx configuration
 
@@ -235,8 +351,8 @@ Unsetting this value is the same as enabling custom nginx config usage.
 {{ .APP }}                          Application name
 {{ .APP_SSL_PATH }}                 Path to SSL certificate and key
 {{ .DOKKU_ROOT }}                   Global Dokku root directory (ex: app dir would be `{{ .DOKKU_ROOT }}/{{ .APP }}`)
-{{ .PROXY_PORT }}                   Non-SSL nginx listener port (same as `DOKKU_PROXY_PORT` config var)
-{{ .PROXY_SSL_PORT }}               SSL nginx listener port (same as `DOKKU_PROXY_SSL_PORT` config var)
+{{ .PROXY_PORT }}                   Non-SSL nginx listener port (same as the `proxy-port` property)
+{{ .PROXY_SSL_PORT }}               SSL nginx listener port (same as the `proxy-ssl-port` property)
 {{ .NOSSL_SERVER_NAME }}            List of non-SSL VHOSTS
 {{ .PROXY_PORT_MAP }}               List of port mappings (same as the `map` ports property)
 {{ .PROXY_UPSTREAM_PORTS }}         List of configured upstream ports (derived from the `map` ports property)
@@ -332,11 +448,13 @@ Changing these value globally or on a per-app basis will require rebuilding the
 | keepalive-timeout         | `75s`                                 | string  | Timeout (with units) during which a keep-alive client connection will stay open on the server side |
 | lingering-timeout         | `5s`                                  | string  | Timeout (with units) is the maximum waiting time for more client data to arrive     |
 | nginx-conf-sigil-path     | `nginx.conf.sigil`                    | string  | Path in the repository to the `nginx.conf.sigil` file                               |
+| nginx-service-command     |                                       | string  | Full path to an executable script or binary to invoke instead of the system's init process when interacting with nginx |
 | proxy-buffer-size         | `8k` (# is os pagesize)               | string  | Size of the buffer used for reading the first part of proxied server response       |
 | proxy-buffering           | `on`                                  | string  | Enables or disables buffering of responses from the proxied server                  |
 | proxy-buffers             | `8 8k`                                | string  | Number and size of the buffers used for reading the proxied server response, for a single connection |
 | proxy-busy-buffers-size   | `16k`                                 | string  | Limits the total size of buffers that can be busy sending a response to the client while the response is not yet fully read. |
 | proxy-connect-timeout     | `60s`                                 | string  | Timeout (with units) for establishing a connection to your backend server           |
+| proxy-keepalive           | empty (disabled)                      | integer | Number of idle keepalive connections to upstream servers (disabled by default)      |
 | proxy-read-timeout        | `60s`                                 | string  | Timeout (with units) for reading response from your backend server                  |
 | proxy-send-timeout        | `60s`                                 | string  | Timeout (with units) for transmitting a request to your backend server              |
 | send-timeout              | `60s`                                 | string  | Timeout (with units) for transmitting a response to your the client                 |
@@ -487,7 +605,7 @@ See the [customizing hostnames documentation](/docs/configuration/domains.md#cus
 
 ### Disabling VHOSTS
 
-See the [disabling vhosts documentation](/docs/configuration/domains.md#disabling-vhosts) for more information on how to disable domain usage for your app.
+See the [enabling and disabling vhosts documentation](/docs/configuration/domains.md#enabling-and-disabling-vhosts) for more information on how to disable domain usage for your app.
 
 ### SSL Configuration
 
@@ -504,3 +622,60 @@ See the [ports documentation](/docs/networking/port-management.md) for more info
 ### Regenerating nginx config
 
 See the [proxy documentation](/docs/networking/proxy-management.md#regenerating-proxy-config) for more information on how to rebuild the nginx proxy configuration for your app.
+
+## Properties
+
+### Settable properties
+
+All nginx-vhosts properties are settable at both the app and global scope.
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `access-log-format` | app + global | none | `--nginx-access-log-format`, `--nginx-global-access-log-format`, `--nginx-computed-access-log-format` | Custom nginx `log_format` directive used for the access log |
+| `access-log-path` | app + global | _`{nginx-log-root}/{app}-access.log`_ | `--nginx-access-log-path`, `--nginx-global-access-log-path`, `--nginx-computed-access-log-path` | Path inside the nginx container where access logs are written |
+| `bind-address-ipv4` | app + global | none | `--nginx-bind-address-ipv4`, `--nginx-global-bind-address-ipv4`, `--nginx-computed-bind-address-ipv4` | IPv4 address the nginx server block binds to |
+| `bind-address-ipv6` | app + global | `::` | `--nginx-bind-address-ipv6`, `--nginx-global-bind-address-ipv6`, `--nginx-computed-bind-address-ipv6` | IPv6 address the nginx server block binds to |
+| `client-body-timeout` | app + global | `60s` | `--nginx-client-body-timeout`, `--nginx-global-client-body-timeout`, `--nginx-computed-client-body-timeout` | Time allowed to read the request body from the client |
+| `client-header-timeout` | app + global | `60s` | `--nginx-client-header-timeout`, `--nginx-global-client-header-timeout`, `--nginx-computed-client-header-timeout` | Time allowed to read the request header from the client |
+| `client-max-body-size` | app + global | `1m` | `--nginx-client-max-body-size`, `--nginx-global-client-max-body-size`, `--nginx-computed-client-max-body-size` | Maximum allowed request body size |
+| `disable-custom-config` | app + global | `false` | `--nginx-disable-custom-config`, `--nginx-global-disable-custom-config`, `--nginx-computed-disable-custom-config` | When `true`, ignores app-supplied `nginx.conf.d/*.conf` snippets |
+| `error-log-path` | app + global | _`{nginx-log-root}/{app}-error.log`_ | `--nginx-error-log-path`, `--nginx-global-error-log-path`, `--nginx-computed-error-log-path` | Path inside the nginx container where error logs are written |
+| `hsts` | app + global | `true` | `--nginx-hsts`, `--nginx-global-hsts`, `--nginx-computed-hsts` | When `true`, emits a `Strict-Transport-Security` header on HTTPS responses |
+| `hsts-include-subdomains` | app + global | `true` | `--nginx-hsts-include-subdomains`, `--nginx-global-hsts-include-subdomains`, `--nginx-computed-hsts-include-subdomains` | Adds the `includeSubDomains` directive to the HSTS header |
+| `hsts-max-age` | app + global | `15724800` | `--nginx-hsts-max-age`, `--nginx-global-hsts-max-age`, `--nginx-computed-hsts-max-age` | `max-age` value (seconds) in the HSTS header |
+| `hsts-preload` | app + global | `false` | `--nginx-hsts-preload`, `--nginx-global-hsts-preload`, `--nginx-computed-hsts-preload` | Adds the `preload` directive to the HSTS header |
+| `keepalive-timeout` | app + global | `75s` | `--nginx-keepalive-timeout`, `--nginx-global-keepalive-timeout`, `--nginx-computed-keepalive-timeout` | Time an idle keep-alive connection stays open |
+| `lingering-timeout` | app + global | `5s` | `--nginx-lingering-timeout`, `--nginx-global-lingering-timeout`, `--nginx-computed-lingering-timeout` | Time nginx waits for more client data when closing a connection |
+| `nginx-conf-sigil-path` | app + global | `nginx.conf.sigil` | `--nginx-nginx-conf-sigil-path`, `--nginx-global-nginx-conf-sigil-path`, `--nginx-computed-nginx-conf-sigil-path` | Path within the app to a custom `nginx.conf.sigil` template |
+| `nginx-service-command` | app + global | none | `--nginx-nginx-service-command`, `--nginx-global-nginx-service-command`, `--nginx-computed-nginx-service-command` | Override command used by `nginx:start`/`nginx:stop`/`nginx:reload` |
+| `proxy-buffer-size` | app + global | _system pagesize_ | `--nginx-proxy-buffer-size`, `--nginx-global-proxy-buffer-size`, `--nginx-computed-proxy-buffer-size` | Buffer size for reading the first part of the upstream response |
+| `proxy-buffering` | app + global | `on` | `--nginx-proxy-buffering`, `--nginx-global-proxy-buffering`, `--nginx-computed-proxy-buffering` | Whether nginx buffers upstream responses (`on` or `off`) |
+| `proxy-buffers` | app + global | _`8 {pagesize}`_ | `--nginx-proxy-buffers`, `--nginx-global-proxy-buffers`, `--nginx-computed-proxy-buffers` | Number and size of buffers used for an upstream response |
+| `proxy-busy-buffers-size` | app + global | _`2 * pagesize`_ | `--nginx-proxy-busy-buffers-size`, `--nginx-global-proxy-busy-buffers-size`, `--nginx-computed-proxy-busy-buffers-size` | Maximum buffer size that can be busy sending a response to the client |
+| `proxy-connect-timeout` | app + global | `60s` | `--nginx-proxy-connect-timeout`, `--nginx-global-proxy-connect-timeout`, `--nginx-computed-proxy-connect-timeout` | Time to establish a connection to the upstream |
+| `proxy-keepalive` | app + global | none | `--nginx-proxy-keepalive`, `--nginx-global-proxy-keepalive`, `--nginx-computed-proxy-keepalive` | Number of idle keep-alive connections to upstream servers held open per worker |
+| `proxy-read-timeout` | app + global | `60s` | `--nginx-proxy-read-timeout`, `--nginx-global-proxy-read-timeout`, `--nginx-computed-proxy-read-timeout` | Time to read a response from the upstream |
+| `proxy-send-timeout` | app + global | `60s` | `--nginx-proxy-send-timeout`, `--nginx-global-proxy-send-timeout`, `--nginx-computed-proxy-send-timeout` | Time to transmit a request to the upstream |
+| `send-timeout` | app + global | `60s` | `--nginx-send-timeout`, `--nginx-global-send-timeout`, `--nginx-computed-send-timeout` | Time between two successive write operations to the client |
+| `underscore-in-headers` | app + global | `off` | `--nginx-underscore-in-headers`, `--nginx-global-underscore-in-headers`, `--nginx-computed-underscore-in-headers` | Whether to allow underscores in client request header field names |
+| `x-forwarded-for-value` | app + global | `$remote_addr` | `--nginx-x-forwarded-for-value`, `--nginx-global-x-forwarded-for-value`, `--nginx-computed-x-forwarded-for-value` | Value used for the `X-Forwarded-For` header |
+| `x-forwarded-port-value` | app + global | `$server_port` | `--nginx-x-forwarded-port-value`, `--nginx-global-x-forwarded-port-value`, `--nginx-computed-x-forwarded-port-value` | Value used for the `X-Forwarded-Port` header |
+| `x-forwarded-proto-value` | app + global | `$scheme` | `--nginx-x-forwarded-proto-value`, `--nginx-global-x-forwarded-proto-value`, `--nginx-computed-x-forwarded-proto-value` | Value used for the `X-Forwarded-Proto` header |
+| `x-forwarded-ssl` | app + global | none | `--nginx-x-forwarded-ssl`, `--nginx-global-x-forwarded-ssl`, `--nginx-computed-x-forwarded-ssl` | Value used for the `X-Forwarded-Ssl` header (e.g. `on`/`off`) |
+
+### Read-only flags
+
+The following flag surfaces in `nginx:report` but is not managed by `nginx:set`:
+
+| Flag | Description |
+|---|---|
+| `--nginx-last-visited-at` | UNIX timestamp of the last request served by nginx for the app |
+
+### Internal properties
+
+The following properties are recorded internally by the plugin and are not exposed via `nginx:report`:
+
+| Property | Description | Source |
+|---|---|---|
+| `proxy-status` | `started`/`stopped` state of the nginx system service | `cmd-nginx-start`/`cmd-nginx-stop` |
+| `nginx-conf-sigil-migrated` | Migration sentinel set the first time a v1 template is rewritten to the current schema | `plugins/nginx-vhosts/install` writes `"true"` once the install-time migration runs |

docs/networking/proxies/openresty.md

@@ -35,7 +35,7 @@ The OpenResty plugin has specific rules for routing requests:
 To use the OpenResty plugin, use the `proxy:set` command for the app in question:
 
 ```shell
-dokku proxy:set node-js-app openresty
+dokku proxy:set node-js-app type openresty
 ```
 
 This will enable the docker label-based OpenResty integration. All future deploys will inject the correct labels for OpenResty to read and route requests to containers. Due to the docker label-based integration used by OpenResty, a single deploy or rebuild will be required before requests will route successfully.
@@ -124,6 +124,56 @@ The following folders within an app repository may have `*.conf` files that will
 - `openresty/http-includes/`: Injected in the `server` block serving http(s) requests for the app.
 - `openresty/http-location-includes/`: Injected in the `location` block that proxies to the app in the app's respective `server` block.
 
+Custom snippets filenames may only include alphanumeric, underscore, and dot characters. For security reasons, filenames that contain other characters will be ignored.
+
+### Label Management
+
+The OpenResty plugin allows you to add custom container labels to apps. These labels are injected into containers during deployment and can be used to configure OpenResty behavior beyond what the plugin provides by default.
+
+Refer to the upstream [openresty-docker-proxy](https://github.com/dokku/openresty-docker-proxy) documentation for more information on what labels are available.
+
+#### Adding a label
+
+To add a custom container label to an app, use the `openresty:labels:add` command:
+
+```shell
+dokku openresty:labels:add node-js-app openresty.directive value
+```
+
+This will add the label `openresty.directive=value` to the app's containers. After adding a label, you will need to rebuild or redeploy the app for the label to be applied to running containers.
+
+```shell
+dokku ps:rebuild node-js-app
+```
+
+#### Removing a label
+
+To remove a custom container label from an app, use the `openresty:labels:remove` command:
+
+```shell
+dokku openresty:labels:remove node-js-app openresty.directive
+```
+
+This will remove the specified label from the app. After removing a label, you will need to rebuild or redeploy the app for the change to be applied to running containers.
+
+```shell
+dokku ps:rebuild node-js-app
+```
+
+#### Showing labels
+
+To view all custom container labels for an app, use the `openresty:labels:show` command:
+
+```shell
+dokku openresty:labels:show node-js-app
+```
+
+To view a specific label value, provide the label name:
+
+```shell
+dokku openresty:labels:show node-js-app openresty.directive
+```
+
 ### SSL Configuration
 
 The OpenResty plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
@@ -227,5 +277,50 @@ dokku openresty:report node-js-app
 You can pass flags which will output only the value of the specific information you want. For example:
 
 ```shell
-dokku openresty:report node-js-app --openresty-letsencrypt-email
+dokku openresty:report node-js-app --openresty-computed-letsencrypt-email
 ```
+
+## Properties
+
+### Settable properties
+
+Five properties (`image`, `log-level`, `letsencrypt-email`, `letsencrypt-server`, `allowed-letsencrypt-domains-func-base64`) are global only. The rest may be set per-app or globally with `--global`; a global value applies to any app that has no per-app value, otherwise the built-in default is used.
+
+Global-only properties expose two report flags: `--openresty-global-<property>` returns the raw stored value (empty when the property has never been set), while `--openresty-computed-<property>` returns the effective value (the global value if set, otherwise the built-in default).
+
+App-or-global properties expose three report flags: `--openresty-<property>` returns the raw per-app value (empty when unset), `--openresty-global-<property>` returns the raw global value (empty when unset), and `--openresty-computed-<property>` returns the effective value, resolving the per-app value first, then the global value, then the built-in default.
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `access-log-format` | app or global | none | `--openresty-access-log-format`, `--openresty-global-access-log-format`, `--openresty-computed-access-log-format` | Custom nginx `log_format` directive used for the access log |
+| `access-log-path` | app or global | _`/var/log/nginx/{app}-access.log`_ | `--openresty-access-log-path`, `--openresty-global-access-log-path`, `--openresty-computed-access-log-path` | Path inside the openresty container where access logs are written |
+| `allowed-letsencrypt-domains-func-base64` | global only | _allow-all stub_ | `--openresty-global-allowed-letsencrypt-domains-func-base64`, `--openresty-computed-allowed-letsencrypt-domains-func-base64` | Base64-encoded Lua function deciding which domains may request a letsencrypt certificate |
+| `bind-address-ipv4` | app or global | none | `--openresty-bind-address-ipv4`, `--openresty-global-bind-address-ipv4`, `--openresty-computed-bind-address-ipv4` | IPv4 address the openresty server block binds to |
+| `bind-address-ipv6` | app or global | `::` | `--openresty-bind-address-ipv6`, `--openresty-global-bind-address-ipv6`, `--openresty-computed-bind-address-ipv6` | IPv6 address the openresty server block binds to |
+| `client-body-timeout` | app or global | `60s` | `--openresty-client-body-timeout`, `--openresty-global-client-body-timeout`, `--openresty-computed-client-body-timeout` | Time allowed to read the request body from the client |
+| `client-header-timeout` | app or global | `60s` | `--openresty-client-header-timeout`, `--openresty-global-client-header-timeout`, `--openresty-computed-client-header-timeout` | Time allowed to read the request header from the client |
+| `client-max-body-size` | app or global | `1m` | `--openresty-client-max-body-size`, `--openresty-global-client-max-body-size`, `--openresty-computed-client-max-body-size` | Maximum allowed request body size |
+| `error-log-path` | app or global | _`/var/log/nginx/{app}-error.log`_ | `--openresty-error-log-path`, `--openresty-global-error-log-path`, `--openresty-computed-error-log-path` | Path inside the openresty container where error logs are written |
+| `hsts` | app or global | `true` | `--openresty-hsts`, `--openresty-global-hsts`, `--openresty-computed-hsts` | When `true`, emits a `Strict-Transport-Security` header on HTTPS responses |
+| `hsts-include-subdomains` | app or global | `true` | `--openresty-hsts-include-subdomains`, `--openresty-global-hsts-include-subdomains`, `--openresty-computed-hsts-include-subdomains` | Adds the `includeSubDomains` directive to the HSTS header |
+| `hsts-max-age` | app or global | `15724800` | `--openresty-hsts-max-age`, `--openresty-global-hsts-max-age`, `--openresty-computed-hsts-max-age` | `max-age` value (seconds) in the HSTS header |
+| `hsts-preload` | app or global | `false` | `--openresty-hsts-preload`, `--openresty-global-hsts-preload`, `--openresty-computed-hsts-preload` | Adds the `preload` directive to the HSTS header |
+| `image` | global only | _parsed from `plugins/openresty-vhosts/Dockerfile`_ | `--openresty-global-image`, `--openresty-computed-image` | Docker image used to run the openresty container |
+| `keepalive-timeout` | app or global | `75s` | `--openresty-keepalive-timeout`, `--openresty-global-keepalive-timeout`, `--openresty-computed-keepalive-timeout` | Time an idle keep-alive connection stays open |
+| `letsencrypt-email` | global only | none | `--openresty-global-letsencrypt-email`, `--openresty-computed-letsencrypt-email` | Contact email enabling letsencrypt; empty disables https issuance |
+| `letsencrypt-server` | global only | `https://acme-v02.api.letsencrypt.org/directory` | `--openresty-global-letsencrypt-server`, `--openresty-computed-letsencrypt-server` | ACME directory used when requesting certificates |
+| `lingering-timeout` | app or global | `5s` | `--openresty-lingering-timeout`, `--openresty-global-lingering-timeout`, `--openresty-computed-lingering-timeout` | Time openresty waits for more client data when closing a connection |
+| `log-level` | global only | `ERROR` | `--openresty-global-log-level`, `--openresty-computed-log-level` | Openresty log level |
+| `proxy-buffer-size` | app or global | _system pagesize_ | `--openresty-proxy-buffer-size`, `--openresty-global-proxy-buffer-size`, `--openresty-computed-proxy-buffer-size` | Buffer size for reading the first part of the upstream response |
+| `proxy-buffering` | app or global | `on` | `--openresty-proxy-buffering`, `--openresty-global-proxy-buffering`, `--openresty-computed-proxy-buffering` | Whether openresty buffers upstream responses (`on` or `off`) |
+| `proxy-buffers` | app or global | _`8 {pagesize}`_ | `--openresty-proxy-buffers`, `--openresty-global-proxy-buffers`, `--openresty-computed-proxy-buffers` | Number and size of buffers used for an upstream response |
+| `proxy-busy-buffers-size` | app or global | _`2 * pagesize`_ | `--openresty-proxy-busy-buffers-size`, `--openresty-global-proxy-busy-buffers-size`, `--openresty-computed-proxy-busy-buffers-size` | Maximum buffer size that can be busy sending a response to the client |
+| `proxy-connect-timeout` | app or global | `60s` | `--openresty-proxy-connect-timeout`, `--openresty-global-proxy-connect-timeout`, `--openresty-computed-proxy-connect-timeout` | Time to establish a connection to the upstream |
+| `proxy-read-timeout` | app or global | `60s` | `--openresty-proxy-read-timeout`, `--openresty-global-proxy-read-timeout`, `--openresty-computed-proxy-read-timeout` | Time to read a response from the upstream |
+| `proxy-send-timeout` | app or global | `60s` | `--openresty-proxy-send-timeout`, `--openresty-global-proxy-send-timeout`, `--openresty-computed-proxy-send-timeout` | Time to transmit a request to the upstream |
+| `send-timeout` | app or global | `60s` | `--openresty-send-timeout`, `--openresty-global-send-timeout`, `--openresty-computed-send-timeout` | Time between two successive write operations to the client |
+| `underscore-in-headers` | app or global | `off` | `--openresty-underscore-in-headers`, `--openresty-global-underscore-in-headers`, `--openresty-computed-underscore-in-headers` | Whether to allow underscores in client request header field names |
+| `x-forwarded-for-value` | app or global | `$remote_addr` | `--openresty-x-forwarded-for-value`, `--openresty-global-x-forwarded-for-value`, `--openresty-computed-x-forwarded-for-value` | Value used for the `X-Forwarded-For` header |
+| `x-forwarded-port-value` | app or global | `$server_port` | `--openresty-x-forwarded-port-value`, `--openresty-global-x-forwarded-port-value`, `--openresty-computed-x-forwarded-port-value` | Value used for the `X-Forwarded-Port` header |
+| `x-forwarded-proto-value` | app or global | `$scheme` | `--openresty-x-forwarded-proto-value`, `--openresty-global-x-forwarded-proto-value`, `--openresty-computed-x-forwarded-proto-value` | Value used for the `X-Forwarded-Proto` header |
+| `x-forwarded-ssl` | app or global | none | `--openresty-x-forwarded-ssl`, `--openresty-global-x-forwarded-ssl`, `--openresty-computed-x-forwarded-ssl` | Value used for the `X-Forwarded-Ssl` header (e.g. `on`/`off`) |

docs/networking/proxies/traefik.md

@@ -32,13 +32,49 @@ The Traefik plugin has specific rules for routing requests:
 - If no `https:443` mapping is found, the first `https` port mapping is used for https requests.
 - If no `https` mapping is found, the container port from `http:80` will be used for https requests.
 - Requests are routed as soon as the container is running and passing healthchecks.
+- Readiness healthchecks defined in `app.json` with a `path` property are automatically transformed into Traefik healthcheck labels.
+
+### Healthchecks
+
+When an app has a readiness healthcheck defined in its `app.json` file with a `path` property, Dokku automatically generates Traefik healthcheck labels. These labels configure Traefik to perform health checks on the container before routing traffic to it.
+
+The following `app.json` healthcheck properties are mapped to Traefik labels:
+
+| app.json Property | Traefik Label Property | Description |
+|-------------------|------------------------|-------------|
+| `path`            | `healthcheck.path`     | The HTTP path to check (required) |
+| `scheme`          | `healthcheck.scheme`   | The scheme to use (`http` or `https`) |
+| `port`            | `healthcheck.port`     | The port to check |
+| `timeout`         | `healthcheck.timeout`  | Timeout in seconds (formatted as `Xs`) |
+| `wait`            | `healthcheck.interval` | Interval between checks in seconds (formatted as `Xs`) |
+
+Example `app.json` configuration:
+
+```json
+{
+  "healthchecks": {
+    "web": [
+      {
+        "name": "web readiness check",
+        "path": "/health",
+        "timeout": 5,
+        "type": "readiness",
+        "wait": 10
+      }
+    ]
+  }
+}
+```
+
+> [!NOTE]
+> Only the first readiness healthcheck with a `path` property is used. Liveness, startup, and command-based healthchecks are not transformed into Traefik labels.
 
 ### Switching to Traefik
 
 To use the Traefik plugin, use the `proxy:set` command for the app in question:
 
 ```shell
-dokku proxy:set node-js-app traefik
+dokku proxy:set node-js-app type traefik
 ```
 
 This will enable the docker label-based Traefik integration. All future deploys will inject the correct labels for Traefik to read and route requests to containers. Due to the docker label-based integration used by Traefik, a single deploy or rebuild will be required before requests will route successfully.
@@ -127,6 +163,54 @@ dokku traefik:set --global log-level DEBUG
 
 After modifying, the Traefik container will need to be restarted.
 
+### Label Management
+
+The Traefik plugin allows you to add custom container labels to apps. These labels are injected into containers during deployment and can be used to configure Traefik behavior beyond what the plugin provides by default.
+
+Refer to the upstream [Traefik](https://doc.traefik.io/traefik/) documentation for more information on what labels are available.
+
+#### Adding a label
+
+To add a custom container label to an app, use the `traefik:labels:add` command:
+
+```shell
+dokku traefik:labels:add node-js-app traefik.directive value
+```
+
+This will add the label `traefik.directive=value` to the app's containers. After adding a label, you will need to rebuild or redeploy the app for the label to be applied to running containers.
+
+```shell
+dokku ps:rebuild node-js-app
+```
+
+#### Removing a label
+
+To remove a custom container label from an app, use the `traefik:labels:remove` command:
+
+```shell
+dokku traefik:labels:remove node-js-app traefik.directive
+```
+
+This will remove the specified label from the app. After removing a label, you will need to rebuild or redeploy the app for the change to be applied to running containers.
+
+```shell
+dokku ps:rebuild node-js-app
+```
+
+#### Showing labels
+
+To view all custom container labels for an app, use the `traefik:labels:show` command:
+
+```shell
+dokku traefik:labels:show node-js-app
+```
+
+To view a specific label value, provide the label name:
+
+```shell
+dokku traefik:labels:show node-js-app traefik.directive
+```
+
 ### SSL Configuration
 
 The traefik plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
@@ -151,6 +235,51 @@ dokku traefik:set --global letsencrypt-server https://acme-staging-v02.api.letse
 
 After enabling, the Traefik container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.
 
+#### Switching to DNS-01 challenge mode
+
+By default, Traefik uses TLS-ALPN-01 challenge for obtaining certificates. To switch to DNS-01 challenge mode (useful for wildcard certificates or when port 443 is not accessible), you need to:
+
+1. Set the challenge mode to `dns`:
+
+```shell
+dokku traefik:set --global challenge-mode dns
+```
+
+2. Set your DNS provider:
+
+```shell
+dokku traefik:set --global dns-provider cloudflare
+```
+
+3. Configure the required environment variables for your DNS provider. Each DNS provider requires specific environment variables. The variable names should be prefixed with `dns-provider-`:
+
+```shell
+dokku traefik:set --global dns-provider-cf_api_email user@example.com
+dokku traefik:set --global dns-provider-cf_api_key your-api-key
+```
+
+The `dns-provider-` prefix will be stripped and the variable name will be uppercased when passed to the Traefik container. For example, `dns-provider-cf_api_email` becomes `CF_API_EMAIL`.
+
+Each configured variable is surfaced by `traefik:report` as `--traefik-global-dns-provider-<env_var>`. As these values are provider credentials, they are masked as `*******` in the default report output, including the aggregate `dokku report`. The raw value is returned when the flag is requested explicitly or when the report is rendered as json:
+
+```shell
+dokku traefik:report --global --traefik-global-dns-provider-cf_api_email
+```
+
+```shell
+dokku traefik:report --global --format json | jq -r '."global-dns-provider-cf_api_email"'
+```
+
+After configuring, the Traefik container will need to be restarted and apps will need to be rebuilt.
+
+Refer to the [Traefik DNS Challenge documentation](https://doc.traefik.io/traefik/https/acme/#dnschallenge) for the list of supported DNS providers and their required environment variables.
+
+To switch back to TLS challenge mode:
+
+```shell
+dokku traefik:set --global challenge-mode tls
+```
+
 ### API Access
 
 Traefik exposes an API and Dashboard, which Dokku disables by default for security reasons. It can be exposed and customized as described below.
@@ -212,37 +341,30 @@ dokku traefik:report
 
 ```
 =====> node-js-app traefik information
-       Traefik api enabled:           false
-       Traefik api vhost:             traefik.dokku.me
-       Traefik basic auth password:   password
-       Traefik basic auth username:   user
-       Traefik dashboard enabled:     false
-       Traefik image:                 traefik:v2.8
-       Traefik letsencrypt email:
-       Traefik letsencrypt server:
-       Traefik log level:             ERROR
-=====> python-app traefik information
-       Traefik api enabled:           false
-       Traefik api vhost:             traefik.dokku.me
-       Traefik basic auth password:   password
-       Traefik basic auth username:   user
-       Traefik dashboard enabled:     false
-       Traefik image:                 traefik:v2.8
-       Traefik letsencrypt email:
-       Traefik letsencrypt server:
-       Traefik log level:             ERROR
-=====> ruby-app traefik information
-       Traefik api enabled:           false
-       Traefik api vhost:             traefik.dokku.me
-       Traefik basic auth password:   password
-       Traefik basic auth username:   user
-       Traefik dashboard enabled:     false
-       Traefik image:                 traefik:v2.8
-       Traefik letsencrypt email:
-       Traefik letsencrypt server:
-       Traefik log level:             ERROR
+       Traefik computed api enabled:      false
+       Traefik computed api vhost:        traefik.dokku.me
+       Traefik computed challenge mode:   tls
+       Traefik computed dashboard enabled: false
+       Traefik computed http entry point: http
+       Traefik computed https entry point: https
+       Traefik computed image:            traefik:v2.8
+       Traefik computed letsencrypt email:
+       Traefik computed letsencrypt server: https://acme-v02.api.letsencrypt.org/directory
+       Traefik computed log level:        ERROR
+       Traefik global api enabled:
+       Traefik global api vhost:
+       Traefik global challenge mode:
+       Traefik global dashboard enabled:
+       Traefik global http entry point:
+       Traefik global https entry point:
+       Traefik global image:
+       Traefik global letsencrypt email:
+       Traefik global letsencrypt server:
+       Traefik global log level:
 ```
 
+The `global-<prop>` keys hold the raw global value and are empty when nothing has been set globally. The `computed-<prop>` keys hold the effective value used at deploy time, falling back to the built-in default when the global value is empty.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -251,19 +373,63 @@ dokku traefik:report node-js-app
 
 ```
 =====> node-js-app traefik information
-       Traefik api enabled:           false
-       Traefik api vhost:             traefik.dokku.me
-       Traefik basic auth password:   password
-       Traefik basic auth username:   user
-       Traefik dashboard enabled:     false
-       Traefik image:                 traefik:v2.8
-       Traefik letsencrypt email:
-       Traefik letsencrypt server:
-       Traefik log level:             ERROR
+       Traefik computed api enabled:      false
+       Traefik computed api vhost:        traefik.dokku.me
+       Traefik computed challenge mode:   tls
+       Traefik computed dashboard enabled: false
+       Traefik computed http entry point: http
+       Traefik computed https entry point: https
+       Traefik computed image:            traefik:v2.8
+       Traefik computed letsencrypt email:
+       Traefik computed letsencrypt server: https://acme-v02.api.letsencrypt.org/directory
+       Traefik computed log level:        ERROR
+       Traefik global api enabled:
+       Traefik global api vhost:
+       Traefik global challenge mode:
+       Traefik global dashboard enabled:
+       Traefik global http entry point:
+       Traefik global https entry point:
+       Traefik global image:
+       Traefik global letsencrypt email:
+       Traefik global letsencrypt server:
+       Traefik global log level:
 ```
 
 You can pass flags which will output only the value of the specific information you want. For example:
 
 ```shell
-dokku traefik:report node-js-app --traefik-api-enabled
+dokku traefik:report node-js-app --traefik-computed-api-enabled
 ```
+
+## Properties
+
+### Settable properties
+
+All traefik properties are global only. Set with `traefik:set --global <property> <value>`.
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `api-enabled` | global only | `false` | `--traefik-global-api-enabled`, `--traefik-computed-api-enabled` | When `true`, enables the Traefik HTTP API |
+| `api-entry-point` | global only | none | `--traefik-global-api-entry-point`, `--traefik-computed-api-entry-point` | Name of the entry point used by the Traefik API |
+| `api-entry-point-address` | global only | none | `--traefik-global-api-entry-point-address`, `--traefik-computed-api-entry-point-address` | Address (`host:port`) the Traefik API listens on |
+| `api-vhost` | global only | `traefik.dokku.me` | `--traefik-global-api-vhost`, `--traefik-computed-api-vhost` | Virtual host that routes to the Traefik API |
+| `basic-auth-password` | global only | none | `--traefik-global-basic-auth-password`, `--traefik-computed-basic-auth-password` (masked as `*******` in the default stdout report; the raw value is returned when queried via `--format json` or when one of these flags is requested explicitly) | Password for basic auth in front of the API/dashboard |
+| `basic-auth-username` | global only | none | `--traefik-global-basic-auth-username`, `--traefik-computed-basic-auth-username` | Username for basic auth in front of the API/dashboard |
+| `challenge-mode` | global only | `tls` | `--traefik-global-challenge-mode`, `--traefik-computed-challenge-mode` | ACME challenge method used by Traefik (`tls`, `http`, or `dns`) |
+| `dashboard-enabled` | global only | `false` | `--traefik-global-dashboard-enabled`, `--traefik-computed-dashboard-enabled` | When `true`, enables the Traefik dashboard |
+| `dns-provider` | global only | none | `--traefik-global-dns-provider`, `--traefik-computed-dns-provider` | Lego DNS provider name used when `challenge-mode` is `dns` |
+| `dns-provider-<ENV_VAR>` | global only | none | `--traefik-global-dns-provider-<env_var>` (masked as `*******` in the default stdout report; the raw value is returned when queried via `--format json` or when this flag is requested explicitly) | Per-provider environment variables passed to the Traefik container; `<ENV_VAR>` is the upstream variable name (e.g. `dns-provider-cloudflare-api-token`) |
+| `http-entry-point` | global only | `http` | `--traefik-global-http-entry-point`, `--traefik-computed-http-entry-point` | Entry point name handling plaintext HTTP traffic |
+| `https-entry-point` | global only | `https` | `--traefik-global-https-entry-point`, `--traefik-computed-https-entry-point` | Entry point name handling TLS-terminated HTTPS traffic |
+| `image` | global only | _parsed from `plugins/traefik-vhosts/Dockerfile`_ | `--traefik-global-image`, `--traefik-computed-image` | Docker image used to run the Traefik container |
+| `letsencrypt-email` | global only | none | `--traefik-global-letsencrypt-email`, `--traefik-computed-letsencrypt-email` | Contact email enabling letsencrypt; empty disables https issuance |
+| `letsencrypt-server` | global only | `https://acme-v02.api.letsencrypt.org/directory` | `--traefik-global-letsencrypt-server`, `--traefik-computed-letsencrypt-server` | ACME directory used when requesting certificates |
+| `log-level` | global only | `ERROR` | `--traefik-global-log-level`, `--traefik-computed-log-level` | Traefik log level |
+
+### Internal properties
+
+The following properties are not managed by `traefik:set` but are recorded internally by the plugin:
+
+| Property | Description | Source |
+|---|---|---|
+| `proxy-status` | `started`/`stopped` state of the traefik compose project | `cmd-traefik-start`/`cmd-traefik-stop` in `plugins/traefik-vhosts/command-functions` |