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

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

.codacy.yml

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

.devcontainer/Dockerfile

@@ -2,7 +2,7 @@ FROM dokku/dokku:latest
 
 RUN apt-get update
 RUN apt-get install --no-install-recommends -y build-essential file nano && \
-  apt-get install --no-install-recommends -y help2man shellcheck uuid-runtime wget xmlstarlet && \
+  apt-get install --no-install-recommends -y software-properties-common help2man shellcheck uuid-runtime wget xmlstarlet && \
   apt-get clean autoclean && \
   apt-get autoremove --yes && \
   rm -rf /var/lib/apt/lists/*

.devcontainer/devcontainer.json

@@ -4,7 +4,9 @@
     "context": ".."
   },
   "containerEnv": {
+    "DOKKU_HOSTNAME": "dokku.me",
     "DOKKU_HOST_ROOT": "${localWorkspaceFolder}/tmp/data/home/dokku",
+    "DOKKU_LIB_HOST_ROOT": "${localWorkspaceFolder}/tmp/data/var/lib/dokku",
     "GO_ROOT_MOUNT": "${localWorkspaceFolder}:/go/src/github.com/dokku/dokku"
   },
   "customizations": {
@@ -29,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/commands/ci-setup

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 set -eo pipefail
-set -x
 
 DOKKU_DOMAIN=${DOKKU_DOMAIN:="dokku.me"}
 

.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

@@ -19,12 +19,12 @@ env:
 
 jobs:
   check-commit:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     outputs:
       skip: ${{ steps.check-commit.outputs.skip }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
@@ -43,7 +43,7 @@ jobs:
 
   build:
     name: build
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     needs: check-commit
     if: ${{ needs.check-commit.outputs.skip != 'true' }}
     outputs:
@@ -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
@@ -70,12 +70,12 @@ jobs:
       - name: set matrix for build
         id: set-matrix
         run: |
-          json=$(python .github/commands/matrix)
+          json=$(python3 .github/commands/matrix)
           echo $json
           echo "matrix=$json" >> $GITHUB_OUTPUT
 
       - name: upload packages
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: build
           path: build
@@ -83,11 +83,11 @@ jobs:
   build-image-amd64:
     name: build-image.linux/amd64
     needs: build
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     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
@@ -111,16 +111,16 @@ jobs:
   unit-tests:
     name: unit.${{ matrix.index }}
     needs: build
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: false
       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
@@ -151,15 +151,15 @@ jobs:
   docker-deploy-tests:
     name: docker
     needs: build
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     strategy:
       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
@@ -167,17 +167,21 @@ jobs:
       - name: ci-setup
         run: ./.github/commands/ci-setup
 
+      - name: docker-container-setup
+        run: |
+          ./tests/ci/setup.sh docker
+
       - name: test docker deploys
         shell: bash
         timeout-minutes: 20
         run: |
-          ./tests/ci/setup.sh docker
+          docker exec dokku bash -c "cat /etc/sudoers.d/dokku-nginx"
           DOKKU_SSH_PORT=3022 sudo -E make -e test-ci-docker
 
   go-tests:
     name: go.${{ matrix.index }}
     needs: build
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: false
       matrix:
@@ -186,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
@@ -210,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
@@ -218,7 +222,7 @@ jobs:
   publish-test-results:
     name: publish-test-results
     needs: unit-tests
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     permissions:
       checks: write
     # the build-and-test job might be skipped, we don't need to run this job then
@@ -226,7 +230,7 @@ jobs:
 
     steps:
       - name: download test-results
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           path: test-results
 
@@ -235,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

@@ -30,7 +30,7 @@ concurrency:
 jobs:
   analyze:
     name: Analyze
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
 
     strategy:
       fail-fast: false
@@ -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

@@ -13,15 +13,15 @@ concurrency:
 
 jobs:
   deploy:
-    runs-on: ubuntu-22.04
+    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

@@ -17,22 +17,22 @@ concurrency:
 jobs:
   hadolint:
     name: hadolint
-    runs-on: ubuntu-22.04
+    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:
     name: markdown-lint
-    runs-on: ubuntu-22.04
+    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'
@@ -44,10 +44,11 @@ jobs:
 
   packer:
     name: packer
-    runs-on: ubuntu-22.04
+    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,35 +57,29 @@ jobs:
         run: "make image/init/digitalocean"
         env:
           PACKER_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - name: Get changed files in the docs folder
-        id: changed-files-specific
-        uses: tj-actions/changed-files@v44.0.0
-        with:
-          files: contrib/images/digitalocean/**
       - name: Run `packer validate`
         env:
           DIGITALOCEAN_TOKEN: ${{ secrets.DIGITALOCEAN_TOKEN }}
-        if: steps.changed-files-specific.outputs.any_changed == 'true'
         run: "make image/validate/digitalocean"
 
   shellcheck:
     name: shellcheck
-    runs-on: ubuntu-22.04
+    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
 
   shfmt:
     name: shfmt
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
       - name: Run shfmt
-        uses: luizm/action-sh-checker@c6edb3de93e904488b413636d96c6a56e3ad671a
+        uses: luizm/action-sh-checker@883217215b11c1fabbf00eb1a9a041f62d74c744
         # v0.5.0 => edd0e45ecff35b05f162052b50df50976c1b74fc
         env:
           SHFMT_OPTS: -l -bn -ci -i 2 -d
@@ -93,10 +88,10 @@ jobs:
 
   yamllint:
     name: yamllint
-    runs-on: ubuntu-22.04
+    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

@@ -19,13 +19,13 @@ on:
 jobs:
   release:
     name: release
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     env:
       PACKAGECLOUD_TOKEN: ${{ secrets.PACKAGECLOUD_TOKEN }}
     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,18 +73,18 @@ 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
 
   build-digitalocean:
     name: build-digitalocean
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     needs: release
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup packer
         uses: hashicorp/setup-packer@main
@@ -109,18 +109,18 @@ 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
 
   bump-azure:
     name: bump-azure
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     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 }}
@@ -136,6 +136,31 @@ jobs:
     runs-on: macos-latest
     needs: release
     steps:
+      - name: Brew doctor
+        run: |
+          brew doctor || true
+      - name: Brew cleanup
+        run: |
+          echo "====> Running brew cleanup"
+          brew cleanup || true
+          echo "====> Untapping homebrew/core"
+          brew untap homebrew/core || true
+          echo "====> Untapping homebrew/cask"
+          brew untap homebrew/cask || true
+          echo "====> Untapping aws/tap"
+          brew untap aws/tap || true
+          echo "====> Untapping hashicorp/tap"
+          brew untap hashicorp/tap || true
+          echo "====> Uninstalling openssl@1.1"
+          brew uninstall openssl@1.1 || true
+          echo "====> Uninstalling ruby@3.0"
+          brew uninstall ruby@3.0 || true
+          echo "====> Running brew cleanup"
+          brew cleanup || true
+      - name: Brew doctor
+        run: brew doctor || true
+      - name: Brew config
+        run: brew config
       - name: Bump Homebrew Formula
         env:
           HOMEBREW_GITHUB_USERNAME: ${{ secrets.HOMEBREW_GITHUB_USERNAME }}

.gitignore

@@ -13,3 +13,4 @@ tmp
 coverage.out
 site
 go.work.sum
+node_modules

.well-known/funding-manifest-urls

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

CONTRIBUTING.md

@@ -97,7 +97,7 @@ need to do
 
 ### Which branch to base the work
 
-All changes should be be based on the latest master commit.
+All changes should be based on the latest master commit.
 
 ### Submitting Changes
 

Dockerfile

@@ -1,4 +1,4 @@
-FROM phusion/baseimage:focal-1.2.0
+FROM phusion/baseimage:noble-1.0.3
 
 CMD ["/sbin/my_init"]
 
@@ -15,26 +15,44 @@ RUN addgroup --gid $DOKKU_GID dokku \
 
 COPY ./tests/dhparam.pem /tmp/dhparam.pem
 COPY ./build/package/ /tmp
+COPY ./contrib/dependencies.json /tmp/dependencies.json
+
+ENV DOKKU_INIT_SYSTEM=sv
 
 SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 # hadolint ignore=DL3005,DL3008
 RUN mkdir -p /etc/apt/keyrings \
   && mkdir -p /etc/apt/keyrings \
+  && apt-get remove -y systemd && apt-get autoremove -y && apt-get update && apt-get -y --no-install-recommends install gpg jq lsb-release openssl openssh-server rsync software-properties-common \
   && curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
   && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null \
   && apt-get update \
   && apt-get -y --no-install-recommends install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin \
+  && PACK_URL="$(jq -r --arg arch "$(dpkg --print-architecture)" '.dependencies[] | select(.name == "pack") | .urls[$arch]' /tmp/dependencies.json)" \
+  && curl -fsSL "$PACK_URL" | tar -C /usr/bin/ --no-same-owner -xzf - pack \
+  && chmod +x /usr/bin/pack \
+  && test -x /usr/bin/pack \
+  && curl -o /tmp/nixpacks.bash -sSL https://nixpacks.com/install.sh \
+  && chmod +x /tmp/nixpacks.bash \
+  && NIXPACKS_BIN_DIR=/usr/bin BIN_DIR=/usr/bin /tmp/nixpacks.bash \
+  && test -x /usr/bin/nixpacks \
+  && rm -rf /tmp/nixpacks.bash \
+  && curl -o /tmp/railpack.bash -sSL https://railpack.com/install.sh \
+  && chmod +x /tmp/railpack.bash \
+  && RAILPACK_BIN_DIR=/usr/bin BIN_DIR=/usr/bin /tmp/railpack.bash \
+  && test -x /usr/bin/railpack \
+  && rm -rf /tmp/railpack.bash \
   && echo "dokku dokku/hostname string $DOKKU_HOSTNAME" | debconf-set-selections \
   && echo "dokku dokku/skip_key_file boolean $DOKKU_SKIP_KEY_FILE" | debconf-set-selections \
   && echo "dokku dokku/vhost_enable boolean $DOKKU_VHOST_ENABLE" | debconf-set-selections \
+  && echo "dokku dokku/install_default_site boolean true" | debconf-set-selections \
   && curl -sSL https://packagecloud.io/dokku/dokku/gpgkey | apt-key add - \
-  && echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ focal main" | tee /etc/apt/sources.list.d/dokku.list \
+  && echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ noble main" | tee /etc/apt/sources.list.d/dokku.list \
   && mkdir -p /etc/nginx/ \
   && cp /tmp/dhparam.pem /etc/nginx/dhparam.pem \
   && apt-get update \
   && apt-get upgrade -y \
-  && apt-get -y --no-install-recommends --only-upgrade install openssl openssh-server \
-  && apt-get -y --no-install-recommends install rsync "/tmp/dokku-$(dpkg --print-architecture).deb" \
+  && apt-get -y --no-install-recommends install lambda-builder "/tmp/dokku-$(dpkg --print-architecture).deb" \
   && apt-get purge -y syslog-ng-core \
   && apt-get autoremove -y \
   && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
@@ -45,6 +63,7 @@ COPY ./docker .
 
 RUN \
   rsync -a /tmp/ / \
+  && chmod +x /usr/local/bin/* \
   && rm -rf /tmp/* \
   && rm /etc/runit/runsvdir/default/sshd/down \
   && chown -R dokku:dokku /home/dokku/ \
@@ -59,8 +78,10 @@ RUN \
   && ln -sf /mnt/dokku/var/lib/dokku/data /var/lib/dokku/data \
   && ln -sf /mnt/dokku/var/lib/dokku/services /var/lib/dokku/services \
   && mv /etc/my_init.d/00_regen_ssh_host_keys.sh /etc/my_init.d/15_regen_ssh_host_keys \
-  && rm -f /usr/bin/systemctl \
   && rm -f /etc/nginx/sites-enabled/default /usr/share/nginx/html/index.html /etc/my_init.d/10_syslog-ng.init \
   && 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-22
+PREBUILT_STACK_URL ?= gliderlabs/herokuish:latest-24
 DOKKU_LIB_ROOT ?= /var/lib/dokku
 PLUGINS_PATH ?= ${DOKKU_LIB_ROOT}/plugins
 CORE_PLUGINS_PATH ?= ${DOKKU_LIB_ROOT}/core-plugins
@@ -54,7 +54,7 @@ go-build:
 	basedir=$(PWD); \
 	for dir in plugins/*; do \
 		if [ -e $$dir/Makefile ]; then \
-			$(MAKE) -e -C $$dir $(PLUGIN_MAKE_TARGET) || exit $$? ;\
+			GO_ARGS='$(GO_ARGS)' CGO_ENABLED=0 GOOS=linux GOARCH=$(GOARCH) GOWORK=off $(MAKE) -e -C $$dir $(PLUGIN_MAKE_TARGET) || exit $$? ;\
 		fi ;\
 	done
 
@@ -64,7 +64,7 @@ ifndef PLUGIN_NAME
 	$(error PLUGIN_NAME not specified)
 endif
 	if [ -e plugins/$(PLUGIN_NAME)/Makefile ]; then \
-		$(MAKE) -e -C plugins/$(PLUGIN_NAME) $(PLUGIN_MAKE_TARGET) || exit $$? ;\
+		GO_ARGS='$(GO_ARGS)' CGO_ENABLED=0 GOOS=linux GOARCH=$(GOARCH) GOWORK=off $(MAKE) -e -C plugins/$(PLUGIN_NAME) $(PLUGIN_MAKE_TARGET) || exit $$? ;\
 	fi
 
 go-clean:
@@ -131,7 +131,7 @@ plugin-dependencies: plugn procfile-util
 plugins: plugn procfile-util docker
 	sudo -E dokku plugin:install --core
 
-dependencies: apt-update docker-image-labeler docker-container-healthchecker lambda-builder netrc sshcommand plugn procfile-util docker help2man man-db sigil dos2unix jq parallel
+dependencies: apt-update jq docker-image-labeler docker-container-healthchecker lambda-builder netrc sshcommand plugn procfile-util docker help2man man-db sigil dos2unix parallel
 	$(MAKE) -e stack
 
 apt-update:
@@ -153,43 +153,36 @@ man-db:
 	apt-get -qq -y --no-install-recommends install man-db
 
 docker-image-labeler:
-	wget -qO /tmp/docker-image-labeler_latest.tgz ${DOCKER_IMAGE_LABELER_URL}
-	tar xzf /tmp/docker-image-labeler_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/docker-image-labeler-${TARGETARCH} /usr/local/bin/docker-image-labeler
+	wget -qO /usr/local/bin/docker-image-labeler ${DOCKER_IMAGE_LABELER_URL}
+	chmod +x /usr/local/bin/docker-image-labeler
 
 docker-container-healthchecker:
-	wget -qO /tmp/docker-container-healthchecker_latest.tgz ${DOCKER_CONTAINER_HEALTHCHECKER_URL}
-	tar xzf /tmp/docker-container-healthchecker_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/docker-container-healthchecker-${TARGETARCH} /usr/local/bin/docker-container-healthchecker
+	wget -qO /usr/local/bin/docker-container-healthchecker ${DOCKER_CONTAINER_HEALTHCHECKER_URL}
+	chmod +x /usr/local/bin/docker-container-healthchecker
 
 lambda-builder:
-	wget -qO /tmp/lambda-builder_latest.tgz ${LAMBDA_BUILDER_URL}
-	tar xzf /tmp/lambda-builder_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/lambda-builder-${TARGETARCH} /usr/local/bin/lambda-builder
+	wget -qO /usr/local/bin/lambda-builder ${LAMBDA_BUILDER_URL}
+	chmod +x /usr/local/bin/lambda-builder
 
 netrc:
-	wget -qO /tmp/netrc_latest.tgz ${NETRC_URL}
-	tar xzf /tmp/netrc_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/netrc-${TARGETARCH} /usr/local/bin/netrc
+	wget -qO /usr/local/bin/netrc ${NETRC_URL}
+	chmod +x /usr/local/bin/netrc
 
 procfile-util:
-	wget -qO /tmp/procfile-util_latest.tgz ${PROCFILE_UTIL_URL}
-	tar xzf /tmp/procfile-util_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/procfile-util-${TARGETARCH} /usr/local/bin/procfile-util
+	wget -qO /usr/local/bin/procfile-util ${PROCFILE_UTIL_URL}
+	chmod +x /usr/local/bin/procfile-util
 
 plugn:
-	wget -qO /tmp/plugn_latest.tgz ${PLUGN_URL}
-	tar xzf /tmp/plugn_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/plugn-${TARGETARCH} /usr/local/bin/plugn
+	wget -qO /usr/local/bin/plugn ${PLUGN_URL}
+	chmod +x /usr/local/bin/plugn
 
 sigil:
-	wget -qO /tmp/sigil_latest.tgz ${SIGIL_URL}
-	tar xzf /tmp/sigil_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/gliderlabs-sigil-${TARGETARCH} /usr/local/bin/sigil
+	wget -qO /usr/local/bin/sigil ${SIGIL_URL}
+	chmod +x /usr/local/bin/sigil
 
 sshcommand:
-	wget -qO /tmp/sshcommand_latest.tgz ${SSHCOMMAND_URL}
-	tar xzf /tmp/sshcommand_latest.tgz -C /usr/local/bin
+	wget -qO /usr/local/bin/sshcommand ${SSHCOMMAND_URL}
+	chmod +x /usr/local/bin/sshcommand
 	sshcommand create dokku /usr/local/bin/dokku
 
 docker:
@@ -233,3 +226,8 @@ vagrant-acl-add:
 
 vagrant-dokku:
 	vagrant ssh -- "sudo -H -u root bash -c 'dokku $(RUN_ARGS)'"
+
+IMAGE_TAG ?= dokku/dokku:latest
+
+test-image-healthcheck:
+	IMAGE_TAG=$(IMAGE_TAG) ./tests/image/healthcheck.sh

README.md

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

Vagrantfile

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

bootstrap.sh

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

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.21.6
+BUILD_IMAGE := golang:1.26.2
 GO_BUILD_CACHE ?= /tmp/dokku-go-build-cache
 GO_MOD_CACHE   ?= /tmp/dokku-go-mod-mod
 GO_ROOT_MOUNT  ?= $$PWD/../..:$(GO_REPO_ROOT)

contrib/build-base.Dockerfile

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

contrib/build-docs

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

contrib/build-dokku.Dockerfile

@@ -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/copy-packages

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

contrib/dependencies.json

@@ -1,107 +1,104 @@
 {
   "dependencies": [
     {
-      "name": "docker-image-labeler",
-      "version": "0.6.1",
+      "name": "docker-container-healthchecker",
+      "version": "0.16.0",
       "urls": {
-        "amd64": "https://github.com/dokku/docker-image-labeler/releases/download/v0.6.1/docker-image-labeler_0.6.1_linux_amd64.tgz",
-        "arm64": "https://github.com/dokku/docker-image-labeler/releases/download/v0.6.1/docker-image-labeler_0.6.1_linux_arm64.tgz",
-        "arm": "https://github.com/dokku/docker-image-labeler/releases/download/v0.6.1/docker-image-labeler_0.6.1_linux_armhf.tgz"
+        "amd64": "https://github.com/dokku/docker-container-healthchecker/releases/download/v0.16.0/docker-container-healthchecker-linux-amd64",
+        "arm64": "https://github.com/dokku/docker-container-healthchecker/releases/download/v0.16.0/docker-container-healthchecker-linux-arm64"
       }
     },
     {
-      "name": "docker-container-healthchecker",
-      "version": "0.9.0",
+      "name": "docker-image-labeler",
+      "version": "0.10.0",
       "urls": {
-        "amd64": "https://github.com/dokku/docker-container-healthchecker/releases/download/v0.9.0/docker-container-healthchecker_0.9.0_linux_amd64.tgz",
-        "arm64": "https://github.com/dokku/docker-container-healthchecker/releases/download/v0.9.0/docker-container-healthchecker_0.9.0_linux_arm64.tgz",
-        "arm": "https://github.com/dokku/docker-container-healthchecker/releases/download/v0.9.0/docker-container-healthchecker_0.9.0_linux_armhf.tgz"
+        "amd64": "https://github.com/dokku/docker-image-labeler/releases/download/v0.10.0/docker-image-labeler-linux-amd64",
+        "arm64": "https://github.com/dokku/docker-image-labeler/releases/download/v0.10.0/docker-image-labeler-linux-arm64"
       }
     },
     {
       "name": "lambda-builder",
-      "version": "0.6.0",
+      "version": "0.9.4",
       "urls": {
-        "amd64": "https://github.com/dokku/lambda-builder/releases/download/v0.6.0/lambda-builder_0.6.0_linux_amd64.tgz",
-        "arm64": "https://github.com/dokku/lambda-builder/releases/download/v0.6.0/lambda-builder_0.6.0_linux_arm64.tgz",
-        "arm": "https://github.com/dokku/lambda-builder/releases/download/v0.6.0/lambda-builder_0.6.0_linux_armhf.tgz"
+        "amd64": "https://github.com/dokku/lambda-builder/releases/download/v0.9.4/lambda-builder-linux-amd64",
+        "arm64": "https://github.com/dokku/lambda-builder/releases/download/v0.9.4/lambda-builder-linux-arm64"
       }
     },
     {
       "name": "netrc",
-      "version": "0.8.0",
+      "version": "0.11.1",
       "urls": {
-        "amd64": "https://github.com/dokku/netrc/releases/download/v0.8.0/netrc_0.8.0_linux_amd64.tgz",
-        "arm64": "https://github.com/dokku/netrc/releases/download/v0.8.0/netrc_0.8.0_linux_arm64.tgz",
-        "arm": "https://github.com/dokku/netrc/releases/download/v0.8.0/netrc_0.8.0_linux_armhf.tgz"
+        "amd64": "https://github.com/dokku/netrc/releases/download/v0.11.1/netrc-linux-amd64",
+        "arm64": "https://github.com/dokku/netrc/releases/download/v0.11.1/netrc-linux-arm64"
+      }
+    },
+    {
+      "name": "pack",
+      "version": "0.40.9",
+      "urls": {
+        "amd64": "https://github.com/buildpacks/pack/releases/download/v0.40.9/pack-v0.40.9-linux.tgz",
+        "arm64": "https://github.com/buildpacks/pack/releases/download/v0.40.9/pack-v0.40.9-linux-arm64.tgz"
       }
     },
     {
       "name": "procfile-util",
-      "version": "0.17.1",
+      "version": "0.20.8",
       "urls": {
-        "amd64": "https://github.com/dokku/procfile-util/releases/download/v0.17.1/procfile-util_0.17.1_linux_amd64.tgz",
-        "arm64": "https://github.com/dokku/procfile-util/releases/download/v0.17.1/procfile-util_0.17.1_linux_arm64.tgz",
-        "arm": "https://github.com/dokku/procfile-util/releases/download/v0.17.1/procfile-util_0.17.1_linux_armhf.tgz"
+        "amd64": "https://github.com/dokku/procfile-util/releases/download/v0.20.8/procfile-util-linux-amd64",
+        "arm64": "https://github.com/dokku/procfile-util/releases/download/v0.20.8/procfile-util-linux-arm64"
       }
     },
     {
       "name": "sshcommand",
-      "version": "0.17.1",
+      "version": "0.20.2",
       "urls": {
-        "amd64": "https://github.com/dokku/sshcommand/releases/download/v0.17.1/sshcommand_0.17.1_linux_x86_64.tgz",
-        "arm64": "https://github.com/dokku/sshcommand/releases/download/v0.17.1/sshcommand_0.17.1_linux_x86_64.tgz",
-        "arm": "https://github.com/dokku/sshcommand/releases/download/v0.17.1/sshcommand_0.17.1_linux_x86_64.tgz"
+        "amd64": "https://github.com/dokku/sshcommand/releases/download/v0.20.2/sshcommand",
+        "arm64": "https://github.com/dokku/sshcommand/releases/download/v0.20.2/sshcommand"
       }
     }
   ],
   "predependencies": [
     {
       "name": "gliderlabs-sigil",
-      "version": "0.10.1",
+      "version": "0.12.1",
       "urls": {
-        "amd64": "https://github.com/gliderlabs/sigil/releases/download/v0.10.1/gliderlabs-sigil_0.10.1_linux_amd64.tgz",
-        "arm64": "https://github.com/gliderlabs/sigil/releases/download/v0.10.1/gliderlabs-sigil_0.10.1_linux_arm64.tgz",
-        "arm": "https://github.com/gliderlabs/sigil/releases/download/v0.10.1/gliderlabs-sigil_0.10.1_linux_armhf.tgz"
+        "amd64": "https://github.com/gliderlabs/sigil/releases/download/v0.12.1/sigil-linux-amd64",
+        "arm64": "https://github.com/gliderlabs/sigil/releases/download/v0.12.1/sigil-linux-arm64"
       }
     },
     {
       "name": "plugn",
-      "version": "0.13.0",
+      "version": "0.17.1",
       "urls": {
-        "amd64": "https://github.com/dokku/plugn/releases/download/v0.13.0/plugn_0.13.0_linux_amd64.tgz",
-        "arm64": "https://github.com/dokku/plugn/releases/download/v0.13.0/plugn_0.13.0_linux_arm64.tgz",
-        "arm": "https://github.com/dokku/plugn/releases/download/v0.13.0/plugn_0.13.0_linux_armhf.tgz"
+        "amd64": "https://github.com/dokku/plugn/releases/download/v0.17.1/plugn-linux-amd64",
+        "arm64": "https://github.com/dokku/plugn/releases/download/v0.17.1/plugn-linux-arm64"
       }
     }
   ],
   "recommendations": [
     {
       "name": "dokku-event-listener",
-      "version": "0.15.0",
+      "version": "0.20.1",
       "urls": {
-        "amd64": "https://github.com/dokku/dokku-event-listener/releases/download/v0.15.0/dokku-event-listener_0.15.0_linux_amd64.tgz",
-        "arm64": "https://github.com/dokku/dokku-event-listener/releases/download/v0.15.0/dokku-event-listener_0.15.0_linux_arm64.tgz",
-        "arm": "https://github.com/dokku/dokku-event-listener/releases/download/v0.15.0/dokku-event-listener_0.15.0_linux_armhf.tgz"
+        "amd64": "https://github.com/dokku/dokku-event-listener/releases/download/v0.20.1/dokku-event-listener-linux-amd64",
+        "arm64": "https://github.com/dokku/dokku-event-listener/releases/download/v0.20.1/dokku-event-listener-linux-arm64"
       }
     },
     {
       "name": "dokku-update",
-      "version": "0.7.2",
+      "version": "0.10.0",
       "urls": {
-        "amd64": "https://github.com/dokku/dokku-update/releases/download/v0.7.2/dokku-update_0.7.2_linux_x86_64.tgz",
-        "arm64": "https://github.com/dokku/dokku-update/releases/download/v0.7.2/dokku-update_0.7.2_linux_x86_64.tgz",
-        "arm": "https://github.com/dokku/dokku-update/releases/download/v0.7.2/dokku-update_0.7.2_linux_x86_64.tgz"
+        "amd64": "https://github.com/dokku/dokku-update/releases/download/v0.10.0/dokku-update",
+        "arm64": "https://github.com/dokku/dokku-update/releases/download/v0.10.0/dokku-update"
       }
     },
     {
       "name": "herokuish",
-      "version": "0.8.0",
+      "version": "0.11.16",
       "urls": {
-        "amd64": "https://github.com/gliderlabs/herokuish/releases/download/v0.8.0/herokuish_0.8.0_linux_x86_64.tgz",
-        "arm64": "https://github.com/gliderlabs/herokuish/releases/download/v0.8.0/herokuish_0.8.0_linux_x86_64.tgz",
-        "arm": "https://github.com/gliderlabs/herokuish/releases/download/v0.8.0/herokuish_0.8.0_linux_x86_64.tgz"
+        "amd64": "https://github.com/gliderlabs/herokuish/releases/download/v0.11.16/herokuish_0.11.16_linux_x86_64.tgz",
+        "arm64": "https://github.com/gliderlabs/herokuish/releases/download/v0.11.16/herokuish_0.11.16_linux_x86_64.tgz"
       }
     }
   ]
-}
+}

contrib/dokku_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/012-dokku-packages

@@ -12,7 +12,7 @@ pkgs=(apache2-utils
   curl
   man-db
 
-  netcat
+  netcat-traditional
   net-tools
 
   parallel
@@ -49,7 +49,7 @@ echo '--> Setting up dokku apt repository'
 curl -fsSL https://packagecloud.io/dokku/dokku/gpgkey -o /etc/apt/keyrings/dokku.asc
 
 cat >/etc/apt/sources.list.d/dokku.list <<EOM
-deb [arch=amd64 signed-by=/etc/apt/keyrings/dokku.asc]  https://packagecloud.io/dokku/dokku/ubuntu/ jammy main
+deb [arch=amd64 signed-by=/etc/apt/keyrings/dokku.asc]  https://packagecloud.io/dokku/dokku/ubuntu/ noble main
 EOM
 
 echo '--> Install dependencies for dokku from new repository'

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

@@ -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++))
@@ -497,7 +497,7 @@ osv=0
 
 if [[ $OS == "Ubuntu" ]]; then
   ost=1
-  if [[ $VER == "22.10" ]] || [[ $VER == "22.04" ]] || [[ $VER == "20.04" ]] || [[ $VER == "18.04" ]] || [[ $VER == "16.04" ]]; then
+  if [[ $VER == "24.04" ]] || [[ $VER == "22.10" ]] || [[ $VER == "22.04" ]] || [[ $VER == "20.04" ]] || [[ $VER == "18.04" ]] || [[ $VER == "16.04" ]]; then
     osv=1
   fi
 
@@ -513,6 +513,9 @@ elif [[ "$OS" =~ Debian.* ]]; then
     11)
       osv=1
       ;;
+    12)
+      osv=1
+      ;;
     *)
       osv=2
       ;;
@@ -538,7 +541,7 @@ elif [[ $OS == "CentOS Stream" ]]; then
   fi
 elif [[ $OS == "Rocky Linux" ]]; then
   ost=1
-  if [[ $VER =~ 8\. ]]; then
+  if [[ $VER =~ 8\. ]] || [[ $VER =~ 9\. ]]; then
     osv=1
   else
     osv=2

contrib/images/digitalocean/packer.pkr.hcl

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

contrib/release-dokku

@@ -134,7 +134,7 @@ fn-publish-package() {
   [[ "$RELEASE_TYPE" == "raspbian" ]] && DIST=raspbian
 
   if [[ "$RELEASE_TYPE" == "raspbian" ]]; then
-    OS_IDS=("buster" "bullseye")
+    OS_IDS=("bullseye" "bookworm" "trixie")
     for OS_ID in "${OS_IDS[@]}"; do
       log-info "(release-dokku) pushing deb to packagecloud.com/${REPOSITORY}/${DIST}"
       package_cloud push "${REPOSITORY}/${DIST}/${OS_ID}" "$PACKAGE_NAME"
@@ -144,7 +144,7 @@ fn-publish-package() {
       fi
     done
   elif [[ "$DIST" == "ubuntu" ]]; then
-    OS_IDS=("focal" "jammy")
+    OS_IDS=("jammy" "noble")
     for OS_ID in "${OS_IDS[@]}"; do
       log-info "(release-dokku) pushing ${RELEASE_TYPE} to packagecloud.com/${REPOSITORY}/${DIST}"
       package_cloud push "${REPOSITORY}/${DIST}/${OS_ID}" "$PACKAGE_NAME"
@@ -155,7 +155,7 @@ fn-publish-package() {
     done
 
     DIST=debian
-    OS_IDS=("buster" "bullseye" "bookworm")
+    OS_IDS=("bullseye" "bookworm" "trixie")
     for OS_ID in "${OS_IDS[@]}"; do
       log-info "(release-dokku) pushing ${RELEASE_TYPE} to packagecloud.com/${REPOSITORY}/${DIST}"
       package_cloud push "${REPOSITORY}/${DIST}/${OS_ID}" "$PACKAGE_NAME"
@@ -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
@@ -225,14 +225,14 @@ fn-repo-update() {
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/development/release-process.md
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/getting-started/install/docker.md
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/getting-started/installation/index.md
-  fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/home.html
+  fn-replace-version "v$CURRENT_VERSION" "v$NEXT_VERSION" docs/home.html
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/template.html
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" README.md
 
   if [[ "$RELEASE" == 'patch' ]]; then
     fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/assets/versions.json
   else
-    versions=$(python -c 'import json,sys;d=json.load(sys.stdin);d["max-versions"].append("'"${NEXT_VERSION}"'"); print(json.dumps(d, indent=2, sort_keys=True))' <docs/assets/versions.json)
+    versions=$(python3 -c 'import json,sys;d=json.load(sys.stdin);d["max-versions"].append("'"${NEXT_VERSION}"'"); print(json.dumps(d, indent=2, sort_keys=True))' <docs/assets/versions.json)
     echo "$versions" >docs/assets/versions.json
     git add docs/assets/versions.json
   fi
@@ -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)

contrib/write-mkdocs

@@ -70,7 +70,7 @@ def get_nav_from_selector(soup: BeautifulSoup, selector: str, docs_dir: str):
                     children = os.listdir(docs_dir + "/" + child_dir)
 
                     children.sort(
-                        key=lambda x: list(map(int, x.split("-")[0].split("."))),
+                        key=lambda x: list(map(int, x.split("-")[0].split("."))) if "." in x else [-1, -1, -1],
                         reverse=True,
                     )
                     children = [child_dir + c for c in children]

deb.mk

@@ -16,7 +16,7 @@ install-from-deb:
 
 	@echo "--> Installing dokku"
 	wget -qO- https://packagecloud.io/dokku/dokku/gpgkey | sudo tee /etc/apt/trusted.gpg.d/dokku.asc
-	@echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ $(shell lsb_release -cs 2>/dev/null || echo "focal") main" | sudo tee /etc/apt/sources.list.d/dokku.list
+	@echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ $(shell lsb_release -cs 2>/dev/null || echo "noble") main" | sudo tee /etc/apt/sources.list.d/dokku.list
 	sudo apt-get update -qq >/dev/null
 	sudo DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true apt-get -qq -y --no-install-recommends install dokku
 
@@ -27,7 +27,7 @@ deb-all: deb-setup deb-dokku
 deb-setup:
 	@echo "-> Updating deb repository and installing build requirements"
 	@sudo apt-get update -qq >/dev/null
-	@sudo DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true apt-get -qq -y --no-install-recommends install gcc git build-essential wget ruby-dev ruby1.9.1 lintian >/dev/null 2>&1
+	@sudo DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true apt-get -qq -y --no-install-recommends install gcc git build-essential wget ruby-dev lintian >/dev/null 2>&1
 	@command -v fpm >/dev/null || sudo gem install fpm --no-ri --no-rdoc
 	@ssh -o StrictHostKeyChecking=no git@github.com || true
 

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.34.2
+Version: 0.38.27
 Section: web
 Priority: optional
 Architecture: amd64
-Depends: apache2-utils, locales, git, cpio, curl, man-db, netcat, sshcommand, docker-engine-cs (>= 17.05.0) | docker-engine (>= 17.05.0) | docker-io (>= 17.05.0) | docker.io (>= 17.05.0) | docker-ce (>= 17.05.0) | docker-ee (>= 17.05.0) | moby-engine, docker-compose-plugin | moby-compose, docker-buildx-plugin | moby-buildx, docker-container-healthchecker, docker-image-labeler, lambda-builder, net-tools, netrc, parallel, procfile-util, rsync, rsyslog, 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, cgroupfs-mount | cgroup-lite, plugn, sudo, python3, debconf
+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/prerm

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

debian/templates

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

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

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

docker/etc/my_init.d/10_dokku_init

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

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

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

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

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

docker/etc/ssh/sshd_config

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

docker/etc/sudoers.d/dokku-docker

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

docs/_build/entrypoint

@@ -3,7 +3,7 @@ set -eo pipefail
 
 write-mkdocs() {
   if [[ -f /usr/src/source/contrib/write-mkdocs ]]; then
-    if ! python /usr/src/source/contrib/write-mkdocs; then
+    if ! python3 /usr/src/source/contrib/write-mkdocs; then
       exit 0
     fi
   fi

docs/_build/requirements.txt

@@ -1,23 +1,23 @@
-beautifulsoup4==4.12.3
-click==8.1.7
+beautifulsoup4==4.15.0
+click==8.4.2
 ghp-import==2.1.0
-importlib-metadata==7.1.0
-Jinja2==3.1.3
-Markdown>=3.2.1,<3.7
-MarkupSafe==2.1.5
+importlib-metadata==9.0.0
+Jinja2==3.1.6
+Markdown>=3.10.3,<3.11
+MarkupSafe==3.0.3
 mergedeep==1.3.4
-mkdocs==1.5.3
+mkdocs==1.6.1
 mkdocs-exclude==1.0.2
-mkdocs-material==9.5.15
+mkdocs-material==9.7.7
 mkdocs-material-extensions==1.3.1
-packaging==24.0
-Pygments==2.17.2
-pymdown-extensions==10.7.1
-pyparsing==3.1.2
+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.1
-pyyaml_env_tag==0.1
-six==1.16.0
-soupsieve==2.5
-watchdog==4.0.0
-zipp==3.18.1
+PyYAML==6.0.3
+pyyaml_env_tag==1.1
+six==1.17.0
+soupsieve==2.9.2
+watchdog==6.0.0
+zipp==4.1.0

docs/advanced-usage/backup-recovery.md

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

@@ -56,14 +56,19 @@ Please keep the above in mind when utilizing deployment tasks.
 
 ### Changing the `app.json` location
 
-When deploying a monorepo, it may be desirable to specify the specific path of the `app.json` file to use for a given app. This can be done via the `app-json:set` command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no `app.json` file.
+The `app.json` is expected to be found in a specific directory, depending on the deploy approach:
 
-For deploys via the `git:from-image` and `git:load-image` commands, the `app.json` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `app.json` extracted directly from the source code. Both cases will respect the configured `appjson-path` property value.
+- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands.
+- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`).
+
+Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `appjson-path` property:
 
 ```shell
 dokku app-json:set node-js-app appjson-path .dokku/app.json
 ```
 
+The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, Dokku will continue the build process as if the repository has no `app.json`.
+
 The default value may be set by passing an empty value for the option:
 
 ```shell
@@ -96,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
@@ -117,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

@@ -3,57 +3,126 @@
 > [!IMPORTANT]
 > New as of 0.3.17
 
-Pass [container options](https://docs.docker.com/engine/reference/run/) to the `docker run` command  during Dokku's `build`, `deploy` and `run` phases
-
 ```
-docker-options:add <app> <phase(s)> OPTION    # Add Docker option to app for phase (comma-separated phase list)
-docker-options:clear <app> [<phase(s)>...]    # Clear a docker options from application
-docker-options:remove <app> <phase(s)> OPTION # Remove Docker option from app for phase (comma-separated phase list)
-docker-options:report [<app>] [<flag>]        # Displays a docker options report for one or more apps
+docker-options:add [--process PROC...] <app> <phase(s)> OPTION    # Add Docker option to app for phase
+docker-options:clear [--process PROC...] <app> [<phase(s)>...]    # Clear docker options from app
+docker-options:list <app> [--process PROC] --phase PHASE          # List docker options for one process+phase pair
+docker-options:remove [--process PROC...] <app> <phase(s)> OPTION # Remove Docker option from app for phase
+docker-options:report [<app>] [<flag>] [--format json|stdout]     # Displays a docker options report for one or more apps
 ```
 
-> When specifying multiple phases, they **must** be comma-separated _without_ spaces in between each phase, like so:
->
-> ```shell
-> dokku docker-options:add node-js-app deploy,run "-v /var/log/node-js-app:/app/logs"
-> ```
+The `docker-options` plugin allows users to specify custom [container options](https://docs.docker.com/engine/reference/run/) for containers created by Dokku at various phases.
 
-## About Dokku phases
+## Usage
 
-Dokku deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to their underlying docker container:
+### Background
 
-- `build`: the container that executes the appropriate buildpack
-- `deploy`: the container that executes your running/deployed application
-- `run`: the container that executes any arbitrary command via `dokku run`
+#### Phases
 
-Manipulation of docker options will not restart running containers. This enables multiple options to be set/unset before final application. As such, changing an app's docker options must be followed by a `dokku ps:rebuild` in order to take effect.
+Dokku deploys your app in multiple "phases" and the `docker-options` plugin allows you to pass arguments to their underlying docker container:
+
+- `build`: The `build` phase is used to provide container options that are available during the build process for use by the various builders.
+    - A given builder may strip out or ignore options that are unsupported by the builder in question - as an example, the `dockerfile` builder does not support mounted volumes.
+- `deploy`: The `deploy` phase is used to provide container options that are set on _deployed_ process types. This covers every process type specified in an app `Procfile` as well as any default processes your app may deploy.
+    - The `deploy` phase is usually the correct phase to add options for running containers.
+- `run`: The `run` phase is used to provide container options to one-off containers created by `dokku run`, `dokku run:detached`, and any cron tasks specified in your `app.json`.
+
+> [!IMPORTANT]
+> The `run` phase does _not_ correspond 1-to-1 to `docker run` or `docker container run` commands. Specifying a container option at the `run` phase will only be invoked on containers created by the `run` plugin and cron tasks. Please be sure to specify options at the correct phase for your use-case.
+
+Adding or removing docker-options will not apply to any running containers, and only applies to containers created _after_ the options have been modified. As such, changing an app's docker options must be followed by a `dokku ps:rebuild` or a deploy in order to take effect.
+
+#### Supported Docker Options
 
 More information on supported Docker options can be found [here](https://docs.docker.com/engine/reference/commandline/run/).
 
 Container options configured via the `docker-options` plugin are not used to modify the process a container runs. Container options are the `[OPTIONS]` portion of the following, where `[CONTAINER_COMMAND]` and `[ARG]` are the process and the arguments passed to it that are launched in the created container: `docker run [OPTIONS] [CONTAINER_COMMAND] [ARG...]`. Please see the documentation for [customizing the run command](/docs/deployment/builders/dockerfiles.md#customizing-the-run-command) or use a [Procfile](/docs/deployment/builders/dockerfiles.md#procfiles-and-multiple-processes) to modify the command used by a Dockerfile-based container.
 
-## Examples
+#### Scheduler support
 
-### Add Docker options
+Docker options are written in Docker's own vocabulary and are passed verbatim to `docker run` by the `docker-local` scheduler. Other schedulers translate only the subset that has an equivalent in their own runtime, and ignore the rest.
 
-Add some options for the deployed/running app and when executing [`dokku run`](/docs/processes/one-off-tasks.md):
+The `k3s` scheduler translates `--cap-add`, `--cap-drop`, `--privileged`, and `--sysctl` into their Kubernetes equivalents. See the [k3s scheduler documentation](/docs/deployment/schedulers/k3s.md) for details, including the restriction that only namespaced sysctls can be set on a pod.
 
 ```shell
-# Mount a host volume in a Docker container: "-v /host/path:/container/path"
-dokku docker-options:add node-js-app deploy "-v /var/log/node-js-app:/app/logs"
-dokku docker-options:add node-js-app run "-v /var/log/node-js-app:/app/logs"
+dokku docker-options:add node-js-app deploy "--sysctl net.ipv4.ip_unprivileged_port_start=1024"
 ```
 
-> [!NOTE]
-> When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory.
+#### Mounting volumes and host directories
 
-### Remove a Docker option
+Docker supports volume and host directory mounting via the `-v` or `--volume` flags. In order to simplify usage, Dokku provides a `storage` plugin as an abstraction to interact with persistent storage. In most cases, the Dokku project recommends using the persistent storage plugin over directly manipulating docker options at different phases. See the [persistent storage documentation](/docs/advanced-usage/persistent-storage.md) for more information on how to attach persistent storage to your app.
+
+### Commands
+
+#### Add Docker options
+
+To add a docker option to an app, use the `docker-options:add` command. This takes an app name, a comma-separated list of phases, and the docker-option to add.
 
 ```shell
-dokku docker-options:remove node-js-app run "-v /var/log/node-js-app:/app/logs"
+dokku docker-options:add node-js-app deploy "--ulimit nofile=12"
 ```
 
-### Clear all Docker options for an app
+Multiple phases can be specified by using a comma when specifying phases:
+
+```shell
+dokku docker-options:add node-js-app deploy,run "--ulimit nofile=12"
+```
+
+Multiple docker options can also be specified in a single call. Each `--flag [value]` group is detected on flag boundaries, shell-tokenized for quoting safety, and stored as its own entry so it round-trips through `docker-options:report` and `docker-options:list`:
+
+```shell
+dokku docker-options:add node-js-app deploy "--ulimit nofile=12" "--shm-size 256m"
+```
+
+Option values are stored and passed to the container verbatim. Quoting only controls how a value is split into words - no shell expansion is performed, so `$(...)`, backticks, `$VAR`, and globs are treated literally rather than being interpreted by the shell. This is what lets values such as a Traefik router rule be applied as-is:
+
+```shell
+dokku docker-options:add node-js-app deploy '--label "traefik.http.routers.web.rule=Host(`node-js-app.example.com`) && PathPrefix(`/api`)"'
+```
+
+> [!WARNING]
+> Options added before 0.38.25 were expanded by the shell when a container was created. Any such option that relied on shell expansion - `$(...)`, backticks, or `$VAR` - is treated as a literal string after upgrading and must be re-added with the value already resolved:
+>
+> ```shell
+> dokku docker-options:remove node-js-app deploy "--group-add \$(getent group docker | cut -d: -f3)"
+> dokku docker-options:add node-js-app deploy "--group-add $(getent group docker | cut -d: -f3)"
+> ```
+
+A misplaced `--process PROC` (i.e. one specified after the app name instead of before it) is honored as a subcommand flag rather than stored as a docker option, so the two invocations below behave identically:
+
+```shell
+dokku docker-options:add --process web node-js-app deploy "--ulimit nofile=12" "--shm-size 256m"
+dokku docker-options:add node-js-app deploy "--ulimit nofile=12" "--shm-size 256m" --process web
+```
+
+#### Remove a Docker option
+
+To remove docker options from an app, use the `docker-options:remove` command. This takes an app name, a comma-separated list of phases, and the docker-option to remove.
+
+```shell
+dokku docker-options:remove node-js-app run "--ulimit nofile=12"
+```
+
+Multiple phases can be specified by using a comma when specifying phases:
+
+```shell
+dokku docker-options:remove node-js-app deploy,run "--ulimit nofile=12"
+```
+
+Multiple docker options can also be removed in a single call, mirroring the splitting that `docker-options:add` performs:
+
+```shell
+dokku docker-options:remove node-js-app deploy "--ulimit nofile=12" "--shm-size 256m"
+```
+
+A stored option is matched by shell word rather than by exact string, so the value only has to be equivalent to the stored one, not byte-identical. Quoting an option one way removes an option that was stored quoted another way:
+
+```shell
+dokku docker-options:add node-js-app deploy "--label 'com.example.owner=platform team'"
+dokku docker-options:remove node-js-app deploy '--label "com.example.owner=platform team"'
+```
+
+#### Clear all Docker options for an app
 
 Docker options can be removed for a specific app using the `docker-options:clear` command.
 
@@ -84,7 +153,7 @@ dokku docker-options:clear node-js-app build,run
 -----> Clearing docker-options for node-js-app on phase run
 ```
 
-### Displaying docker-options reports for an app
+#### Displaying docker-options reports for an app
 
 > [!IMPORTANT]
 > New as of 0.8.1
@@ -98,8 +167,8 @@ dokku docker-options:report
 ```
 =====> node-js-app docker options information
        Docker options build:
-       Docker options deploy: -v /var/log/node-js-app:/app/logs
-       Docker options run:  -v /var/log/node-js-app:/app/logs
+       Docker options deploy: --ulimit nofile=12 --shm-size 256m
+       Docker options run:  --ulimit nofile=12 --shm-size 256m
 =====> python-sample docker options information
        Docker options build:
        Docker options deploy:
@@ -128,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.34.2 enabled    dokku core standard plugin
-  20_events            0.34.2 enabled    dokku core events logging plugin
-  app-json             0.34.2 enabled    dokku core app-json plugin
-  apps                 0.34.2 enabled    dokku core apps plugin
-  build-env            0.34.2 enabled    dokku core build-env plugin
-  buildpacks           0.34.2 enabled    dokku core buildpacks plugin
-  certs                0.34.2 enabled    dokku core certificate management plugin
-  checks               0.34.2 enabled    dokku core checks plugin
-  common               0.34.2 enabled    dokku core common plugin
-  config               0.34.2 enabled    dokku core config plugin
-  docker-options       0.34.2 enabled    dokku core docker-options plugin
-  domains              0.34.2 enabled    dokku core domains plugin
-  enter                0.34.2 enabled    dokku core enter plugin
-  git                  0.34.2 enabled    dokku core git plugin
-  logs                 0.34.2 enabled    dokku core logs plugin
-  network              0.34.2 enabled    dokku core network plugin
-  nginx-vhosts         0.34.2 enabled    dokku core nginx-vhosts plugin
-  plugin               0.34.2 enabled    dokku core plugin plugin
-  proxy                0.34.2 enabled    dokku core proxy plugin
-  ps                   0.34.2 enabled    dokku core ps plugin
-  repo                 0.34.2 enabled    dokku core repo plugin
-  resource             0.34.2 enabled    dokku core resource plugin
-  scheduler-docker-local 0.34.2 enabled    dokku core scheduler-docker-local plugin
-  shell                0.34.2 enabled    dokku core shell plugin
-  ssh-keys             0.34.2 enabled    dokku core ssh-keys plugin
-  storage              0.34.2 enabled    dokku core storage plugin
-  tags                 0.34.2 enabled    dokku core tags plugin
-  tar                  0.34.2 enabled    dokku core tar plugin
-  trace                0.34.2 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.34.0-migration-guide.md

@@ -17,3 +17,7 @@
     ```shell
     dokku scheduler-k3s:set --global ingress-class traefik
     ```
+
+## Deprecations
+
+The `pre-deploy` plugin trigger is deprecated as of `0.34.4`. It is currently invoked during the `post-release-builder` plugin trigger, where image mutation is heavily discouraged. Users should instead move any trigger usage to the `pre-release-builder` plugin trigger. The `pre-deploy` plugin trigger will be removed in a future release.

docs/appendices/0.35.0-migration-guide.md

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

docs/appendices/0.36.0-migration-guide.md

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

docs/appendices/0.37.0-migration-guide.md

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

docs/appendices/0.38.0-migration-guide.md

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

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

@@ -0,0 +1,301 @@
+# app.json
+
+`app.json` is a manifest format for describing web apps. It declares cron tasks, healthchecks, and other information required to run an app on Dokku. This document describes the schema in detail.
+
+> [!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
+{
+  "cron": [
+    {
+      "command": "echo 'hello'",
+      "schedule": "0 1 * * *"
+    }
+  ]
+}
+```
+
+(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
+
+```json
+{
+  "formation": {
+    "web": {
+      "max_parallel": 1,
+      "quantity": 1
+    }
+  }
+}
+```
+
+(object, optional) A key-value object for process type configuration. Keys are the names of the process types. The values are an object containing one or more of the following properties:
+
+- `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
+
+```json
+{
+  "formation": {  
+    "web": {
+      "autoscaling": {
+        "cooldown_period_seconds": 300,
+        "max_quantity": 10,
+        "min_quantity": 1,
+        "polling_interval_seconds": 30,
+        "triggers": {
+          "http": {
+            "metadata": {
+              "url": "https://example.com/health"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+(object, optional) A key-value object for autoscaling configuration. Keys are the names of the process types. The values are an object containing one or more of the following properties:
+
+- `cooldown_period_seconds`: (int, optional)
+- `max_quantity`: (int, optional)
+- `min_quantity`: (int, optional)
+- `polling_interval_seconds`: (int, optional)
+- `triggers`: (object, optional)
+
+An autoscaling trigger consists of the following properties:
+
+- `name`: (string, optional)
+- `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
+{
+  "healthchecks": {
+    "web": [
+      {
+        "type":        "startup",
+        "name":        "web check",
+        "description": "Checking if the app responds to the /health/ready endpoint",
+        "path":        "/health/ready",
+        "attempts": 3
+      }
+    ]
+  }
+}
+```
+
+(object, optional) A key-value object specifying healthchecks to run for a given process type.
+
+- `attempts`: (int, optional)
+- `command`: (list of strings, optional)
+- `content`: (string, optional)
+- `httpHeaders`: (list of header objects, optional)
+- `initialDelay`: (int, optional)
+- `listening`: (boolean, optional)
+- `name`: (string, optional)
+- `path`: (string, optional)
+- `port`: (int, optional)
+- `scheme`: (string, optional)
+- `timeout`: (int, optional)
+- `type`: (string, optional)
+- `uptime`: (int, optional)
+- `wait`: (int, optional)
+- `warn`: (boolean, optional)
+- `onFailure`: (object, optional)
+
+## Scripts
+
+```json
+{
+  "scripts": {
+    "dokku": {
+      "predeploy": "touch /app/predeploy.test",
+      "postdeploy": "curl https://some.external.api.service.com/deployment?state=success"
+    },
+    "postdeploy": "curl https://some.external.api.service.com/created?state=success"
+  }
+}
+```
+
+(object, optional) A key-value object specifying scripts or shell commands to execute at different stages in the build/release process.
+
+- `dokku.predeploy`: (string, optional)
+    - When to use: This should be used if your app does not support arbitrary build commands and you need to make changes to the built image.
+    - Are changes committed to the image at this phase: Yes
+    - Example use-cases
+        - Bundling assets in a slightly different way
+        - Installing a custom package from source or copying a binary into place
+- `dokku.postdeploy`: (string, optional)
+    - When to use: This should be used in conjunction with external systems to signal the completion of your deploy.
+    - Are changes committed to the image at this phase: No
+    - Example use-cases
+        - Notifying slack that your app is deployed
+        - Coordinating traffic routing with a central load balancer
+- `postdeploy`: (string, optional)
+    - When to use: This should be used when you wish to run a command _once_, after the app is created and not on subsequent deploys to the app.
+    - Are changes committed to the image at this phase: No
+    - 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/buildpacks-file.md

@@ -0,0 +1,14 @@
+# .buildpacks
+
+The `.buildpacks` file is used to specify the buildpacks for an application. It is a list of buildpack URLs.
+
+```shell
+https://github.com/heroku/heroku-buildpack-nodejs.git
+https://github.com/heroku/heroku-buildpack-ruby.git
+```
+
+When installed, a buildpack is checked to see if it is a git repository via `git ls-remote`. If it is not, the buildpack is checked to see if it ends in `.tgz`, `.tar.gz`, `.tbz`, `tar.bz`, or `.tar` and is downloaded/extracted before being executed.
+
+If the buildpack is located on Github, a shorthand can be used in the form of `organization/buildpack-name`. This will be expanded to the `https://github.com/organization/heroku-buildpack-buildpack-name.git`. The `heroku-community` organization name is treated as `heroku`.
+
+Comments are not allowed in the `.buildpacks` file.

docs/appendices/file-formats/dockerfile.md

@@ -0,0 +1,3 @@
+# Dockerfile
+
+A Dockerfile is used to build a Docker image for an application. Please refer to the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/) for more information.

docs/appendices/file-formats/lambda-yml.md

@@ -0,0 +1,16 @@
+# lambda.yml
+
+The `lambda.yml` file is used to configure a Lambda application.
+
+```yaml
+---
+build_image: mlupin/docker-lambda:dotnetcore3.1-build
+builder: dotnet
+run_image: mlupin/docker-lambda:dotnetcore3.1
+```
+
+## Fields
+
+`build_image`: A docker image that is accessible by the docker daemon. The `build_image` should be based on an existing Lambda image - builders may fail if they cannot run within the specified `build_image`. The build will fail if the image is inaccessible by the docker daemon.
+`builder`: The name of a builder. This may be used if multiple builders match and a specific builder is desired. If an invalid builder is specified, the build will fail.
+`run_image`: A docker image that is accessible by the docker daemon. The `run_image` should be based on an existing Lambda image - built images may fail to start if they are not compatible with the produced artifact. The generation of the `run_image` will fail if the image is inaccessible by the docker daemon.

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

@@ -0,0 +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/nixpacks-toml.md

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

docs/appendices/file-formats/procfile.md

@@ -0,0 +1,48 @@
+# Procfile
+
+A Procfile is a file that was [promoted by Heroku](https://blog.heroku.com/the_new_heroku_1_process_model_procfile) for their platform as an easy way to specify one or more distinct processes to run within Heroku. This format has since been picked up by various other tools and platforms.
+
+## General Overview
+
+The `procfile-util` tool expects a Procfile to be defined as one or more lines containing one of:
+
+- a comment (preceeded by a `#` symbol or two `//` characters)
+- a process-type/command combination (with optional trailing whitespace or trailing comment)
+    - when there is a trailing comment, the `#` symbol/`//` characters _must_ be preceeded by one or more `whitespace` characters.
+- a blank line (with optional trailing whitespace)
+
+Comments and blank lines are ignored, while process-type/command combinations look like the following:
+
+```
+<process type>: <command>
+```
+
+The syntax is defined as follows:
+
+- `<process type>` – any character in the class `[A-Za-z0-9_-]+`, a process type is a name for your command, such as `web`, `worker`, `urgentworker`, `clock`, etc.
+- `<command>` – a command used to launch the process, such as `rake jobs:work`
+
+Additional rules are as follows:
+
+- contain at most 63 characters
+
+A Procfile that does not match any of the above rules will be considered invalid, and not be processed. This is to avoid issues where a Procfile may contain merge conflicts or other improper content, thus resulting in unwanted runtime behavior for applications.
+
+Finally, process types within a Procfile may not overlap and must be unique. Rather than assuming that the last or first specified is correct, `procfile-util` will fail to parse the Procfile with the relevant error.
+
+### Strict Mode
+
+> Strict mode can be triggered on `procfile-util` via the `--strict` flag.
+
+In strict mode, the character set of a process type changes.
+
+- `<process type>` – a valid DNS Label Name as per [RFC 1123](https://tools.ietf.org/html/rfc1123), a process type is a name for your command, such as `web`, `worker`, `urgentworker`, `clock`, etc.
+
+This syntax differs common interpretations of valid `<process type>` values in that we define the process type as a DNS Label name, versus the regex `[A-Za-z0-9_]+`. The reason for this is that processes defined within Procfiles are commonly used in DNS entries. Rather than have a second level of platform-specific validation in place, this project implicitly defines the format for the process-type.
+
+Given the above, a valid process type can be generalized to the following rules (as taken from the [Kubernetes documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names)):
+
+- contain at most 63 characters
+- contain only lowercase alphanumeric characters or '-'
+- start with an alphanumeric character
+- end with an alphanumeric character

docs/appendices/file-formats/project-toml.md

@@ -0,0 +1,3 @@
+# project.toml
+
+The project descriptor file allows app developers to provide configuration for apps deployed to Dokku via the `pack` builder. Please refer to the [project.toml documentation](https://buildpacks.io/docs/reference/config/project-descriptor/) for more information.

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.34.2/docs/assets/favicons/mstile-70x70.png"/>
-      <square150x150logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.34.2/docs/assets/favicons/mstile-150x150.png"/>
-      <square310x310logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.34.2/docs/assets/favicons/mstile-310x310.png"/>
-      <wide310x150logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.34.2/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.34.2\/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.34.2\/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.34.2\/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.34.2\/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.34.2\/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.34.2\/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

@@ -31,6 +31,10 @@
     "0.31.5",
     "0.32.4",
     "0.33.9",
-    "0.34.2"
+    "0.34.9",
+    "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,8 +125,8 @@ 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+               |
 | [Monit (Health Checks)](https://github.com/mbreit/dokku-monit)                                    | [mbreit][]            | 0.8.0+                |
 | [Monit](https://github.com/cjblomqvist/dokku-monit)                                               | [cjblomqvist][]       | 0.3.x                 |
@@ -151,6 +153,7 @@ The following plugins are available and provided by Dokku maintainers.  Please f
 | ------------------------------------------------------------------------------------------------- | --------------------- | --------------------- |
 | [Chef cookbook](https://github.com/nickcharlton/dokku-cookbook)                                   | [nickcharlton][]      |                       |
 | [Discourse](https://github.com/badsyntax/dokku-discourse)                                         | [badsyntax][]         | 0.21.4+               |
+| [Tailscale](https://github.com/andrew-womeldorf/dokku-tailscale)                                  | [andrew-womeldorf][]  | 0.34.4+               |
 | [Wordpress](https://github.com/dokku-community/dokku-wordpress)                                   | [dokku-community][]   | 0.4.0+                |
 
 ### Deprecated Plugins
@@ -251,6 +254,7 @@ The following plugins are no longer maintained by their developers.
 [alexanderbeletsky]: https://github.com/alexanderbeletsky
 [alexkruegger]: https://github.com/alexkruegger
 [aluxian]: https://github.com/aluxian
+[andrew-womeldorf]: https://github.com/andrew-womeldorf
 [aomitayo]: https://github.com/aomitayo
 [apmorton]: https://github.com/apmorton
 [artofrawr]: https://github.com/artofrawr
@@ -264,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
@@ -319,6 +325,7 @@ The following plugins are no longer maintained by their developers.
 [sekjun9878]: https://github.com/sekjun9878
 [statianzo]: https://github.com/statianzo
 [stuartpb]: https://github.com/stuartpb
+[Tashows]: https://github.com/Tashows
 [thrashr888]: https://github.com/thrashr888
 [wmluke]: https://github.com/wmluke
 [zenedith]: https://github.com/zenedith

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:
@@ -39,13 +39,26 @@ dokku config:set node-js-app KEY="VAL\ WITH\ SPACES"
 Dokku can also read base64 encoded values. That's the easiest way to set a value with newlines or spaces. To set a value with newlines you need to base64 encode it first and pass the `--encoded` flag:
 
 ```shell
-dokku config:set --encoded node-js-app KEY="$(base64 ~/.ssh/id_rsa)"
+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).
@@ -128,7 +131,7 @@ dokku certs:report node-js-app --ssl-enabled
 
 ## HSTS Header
 
-The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. Dokku does enables this header by default for HTTPS requests.
+The [HSTS header](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) is an HTTP header that can inform browsers that all requests to a given site should be made via HTTPS. Dokku enables this header by default for HTTPS requests.
 
 See the [NGINX HSTS documentation](/docs/networking/proxies/nginx.md#hsts-header) for more information on how the HSTS configuration can be managed for your application.
 
@@ -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 issuesare 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:
 
@@ -62,14 +53,19 @@ dokku builder:set node-js-app selected pack
 
 ### Changing the `project.toml` location
 
-When deploying a monorepo, it may be desirable to specify the specific path of the `project.toml` file to use for a given app. This can be done via the `builder-pack:set` command. If a value other than `project.toml` is specified and that file does not exist in the app's build directory, Dokku will continue the build process as if the repository has no `project.toml`.
+The `project.toml` is expected to be found in a specific directory, depending on the deploy approach:
 
-For deploys via the `git:from-image` and `git:load-image` commands, the `project.toml` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `project.toml` extracted directly from the source code. Both cases will respect the configured `projecttoml-path` property value.
+- 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 `projecttoml-path` property:
 
 ```shell
 dokku builder-pack:set node-js-app projecttoml-path .dokku/project.toml
 ```
 
+The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, Dokku will continue the build process as if the repository has no `project.toml`.
+
 The default value may be set by passing an empty value for the option:
 
 ```shell
@@ -102,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
@@ -123,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
 ```
 
@@ -142,7 +140,7 @@ project2.toml
 > [!IMPORTANT]
 > New as of 0.23.0
 
-The default stack builder in use by CNB buildpacks in Dokku is based on `heroku/builder:22`. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command.
+The default stack builder in use by CNB buildpacks in Dokku is based on `heroku/builder:24`. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command.
 
 ```shell
 dokku buildpacks:set-property node-js-app stack paketobuildpacks/build:base-cnb
@@ -156,7 +154,7 @@ dokku buildpacks:set-property node-js-app stack
 
 A change in the stack builder value will execute the `post-stack-set` trigger.
 
-Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_CNB_BUILDER` environment variable (`heroku/builder:22` by default).
+Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_CNB_BUILDER` environment variable (`heroku/builder:24` by default).
 
 ```shell
 # set globally
@@ -169,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

@@ -37,14 +37,19 @@ dokku ports:clear node-js-app
 
 > The previous method to perform this - via `docker-options:add` - should be removed in favor of the `builder-dockerfile:set` command outlined here.
 
-When deploying a monorepo, it may be desirable to specify the specific path of the `Dockerfile` file to use for a given app. This can be done via the `builder-dockerfile:set` command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.
+The `Dockerfile` is expected to be found in a specific directory, depending on the deploy approach:
 
-For git push, `git:from-archive`, and `git:sync` workflows, the `Dockerfile` is extracted directly from the source code, respecting the configured `dockerfile-path` property value.
+- 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 `dockerfile-path` property:
 
 ```shell
-dokku builder-dockerfile:set node-js-app dockerfile-path Dockerfile2
+dokku builder-dockerfile:set node-js-app dockerfile-path .dokku/Dockerfile
 ```
 
+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
@@ -77,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
@@ -98,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
 ```
 
@@ -125,7 +132,7 @@ dokku docker-options:add node-js-app build '--build-arg NODE_ENV'
 Once set, the Dockerfile usage would be as follows:
 
 ```Dockerfile
-FROM ubuntu:20.04
+FROM ubuntu:24.04
 
 # set the argument default
 ARG NODE_ENV=production
@@ -137,7 +144,7 @@ RUN echo $NODE_ENV
 You may also set the argument as an environment variable
 
 ```Dockerfile
-FROM ubuntu:20.04
+FROM ubuntu:24.04
 
 # set the argument default
 ARG NODE_ENV=production
@@ -180,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"]
@@ -189,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
 
@@ -206,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]
@@ -166,7 +62,7 @@ dokku buildpacks:set-property node-js-app stack
 
 A change in the stack builder value will execute the `post-stack-set` trigger.
 
-Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_IMAGE` environment variable (`gliderlabs/herokuish:latest-22` by default).
+Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_IMAGE` environment variable (`gliderlabs/herokuish:latest-24` by default).
 
 ```shell
 # set globally
@@ -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-22
-       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-22
-       Buildpacks global stack:    gliderlabs/herokuish:latest-22
-       Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git,https://github.com/heroku/heroku-buildpack-python.git
-       Buildpacks stack:
-=====> ruby-sample buildpacks information
-       Buildpacks computed stack:  gliderlabs/herokuish:latest-22
-       Buildpacks global stack:    gliderlabs/herokuish:latest-22
-       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

@@ -42,14 +42,19 @@ The `lambda` builder plugin delegates all build logic to [lambda-builder](https:
 
 ### Changing the `lambda.yml` location
 
-When deploying a monorepo, it may be desirable to specify the specific path of the `lambda.yml` file to use for a given app. This can be done via the `builder-lambda:set` command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.
+The `lambda.yml` is expected to be found in a specific directory, depending on the deploy approach:
 
-For deploys via the `git:from-image` and `git:load-image` commands, the `lambda.yml` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `lambda.yml` extracted directly from the source code. Both cases will respect the configured `lambdayml-path` property value.
+- 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 `lambdayml-path` property:
 
 ```shell
 dokku builder-lambda:set node-js-app lambdayml-path .dokku/lambda.yml
 ```
 
+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
@@ -79,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
@@ -100,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
 ```
 
@@ -113,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

@@ -47,12 +47,19 @@ dokku docker-options:add node-js-app build '--env NODE_ENV=production'
 
 ### Changing the `nixpacks.toml` location
 
-When deploying a monorepo, it may be desirable to specify the specific path of the `nixpacks.toml` file to use for a given app. This can be done via the `builder-nixpacks:set` command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.
+The `nixpacks.toml` 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 `nixpackstoml-path` property:
 
 ```shell
-dokku builder-nixpacks:set node-js-app nixpackstoml-path nixpacks2.toml
+dokku builder-nixpacks:set node-js-app nixpackstoml-path .dokku/nixpacks.toml
 ```
 
+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
@@ -73,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
@@ -108,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
@@ -138,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/null.md

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

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

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