feat: implement build tracking

The DOKKU_PID now never gets overwritten except in the case that DOKKU is executed by the sudo user. If the command ends up executing a deploy, then the pid of the `dokku` owned process - which may have been executed via sudo - will be written to the file lock, allowing future commands to interact with the original process.

Additionally, the new builds plugin can be used to handle killing a build.

docs/deployment/builds-management.md

@@ -0,0 +1,30 @@
+# Build Management
+
+> New as of 0.19.0
+
+```
+builds:cancel <app> # Cancel a running build for an app
+builds:list <app> # List all running builds
+builds:output <app> # Shows build output
+builds:report [<app>] [<flag>] # Displays a build report for one or more apps
+```
+
+## Usage
+
+### Listing running deploys
+
+### Viewing the status of a deploy
+
+### Viewing build output for a deploy
+
+### Canceling a running deploy
+
+It can be useful to kill a deploy if that deploy does not appear to be progressing, is impacting other apps through system resource utilization, or if a successful deploy will result in app errors. To do so, the `builds:cancel` command can be used:
+
+```shell
+dokku builds:cancel node-js-app
+```
+
+This command will send a `QUIT` signal to the Process Group ID of the process handling the deploy, and should terminate all processes within that process tree. Finally, it will unlock the deploy so that a new deploy may be immediately invoked.
+
+> Warning: This may also result in invalid app state depending upon when the app deploy was killed.

dokku

@@ -55,7 +55,7 @@ export DOKKU_SYSTEM_USER=${DOKKU_SYSTEM_USER:="dokku"}
 export DOKKU_API_VERSION=1
 export DOKKU_NOT_IMPLEMENTED_EXIT=10
 export DOKKU_VALID_EXIT=0
-export DOKKU_PID="$BASHPID"
+export DOKKU_PID="${DOKKU_PID:=$BASHPID}"
 
 export DOKKU_LOGS_DIR=${DOKKU_LOGS_DIR:="/var/log/dokku"}
 export DOKKU_LOGS_HOST_DIR=${DOKKU_LOGS_HOST_DIR:=$DOKKU_LOGS_DIR}
@@ -88,7 +88,7 @@ fi
 ! has_tty && DOKKU_QUIET_OUTPUT=1
 
 if [[ $(id -un) != "dokku" ]]; then
- unset TMP TMPDIR TEMP TEMPDIR
+ unset DOKKU_PID TMP TMPDIR TEMP TEMPDIR
  if [[ ! $1 =~ plugin:* ]] && [[ $1 != "ssh-keys:add" ]] && [[ $1 != "ssh-keys:remove" ]] && [[ $1 != "scheduler-k3s:initialize" ]] && [[ $1 != "scheduler-k3s:uninstall" ]]; then
  export SSH_USER=$(id -un)
  sudo -u dokku -E -H "$0" "$@"

plugins/builds/commands

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+[[ " help builds:help " == *" $1 "* ]] || exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
+source "$PLUGIN_AVAILABLE_PATH/builds/internal-functions"
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+
+case "$1" in
+ help | builds:help)
+ cmd-builds-help "$@"
+ ;;
+
+ *)
+ exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
+ ;;
+
+esac

plugins/builds/internal-functions

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+
+fn-builds-help-content() {
+ declare desc="return logs plugin help content"
+ cat <<help_content
+ builds, Manage running builds
+ builds:cancel <app>, Cancel a running build for an app
+ builds:list <app>, List all running builds
+ builds:output <app>, Shows build output
+ builds:report [<app>] [<flag>], Displays a build report for one or more apps
+help_content
+}
+
+cmd-builds-help() {
+ if [[ $1 == "builds:help" ]]; then
+ echo -e 'Usage: dokku builds[:COMMAND]'
+ echo ''
+ echo 'Manage running builds'
+ echo ''
+ echo 'Additional commands:'
+ fn-builds-help-content | sort | column -c2 -t -s,
+ elif [[ $(ps -o command= $PPID) == *"--all"* ]]; then
+ fn-builds-help-content
+ else
+ cat <<help_desc
+ builds, Manage running builds
+help_desc
+ fi
+}

plugins/builds/plugin.toml

@@ -0,0 +1,4 @@
+[plugin]
+description = "dokku core builds plugin"
+version = "0.33.6"
+[plugin.config]

plugins/builds/subcommands/cancel

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+
+cmd-builds-cancel() {
+ declare desc="cancel a running build for an app"
+ declare cmd="builds:cancel"
+ [[ "$1" == "$cmd" ]] && shift 1
+ declare APP="$1"
+ verify_app_name "$APP"
+
+ local APP_DEPLOY_LOCK_FILE PROCESS_ID PROCESS_GROUP_ID
+ APP_DEPLOY_LOCK_FILE="$DOKKU_ROOT/$APP/.deploy.lock"
+ if [[ ! -f "$APP_DEPLOY_LOCK_FILE" ]]; then
+ dokku_log_info1 "No matching app deploy found"
+ return
+ fi
+
+ PROCESS_ID="$(cat "$APP_DEPLOY_LOCK_FILE")"
+ if [[ -z "$PROCESS_ID" ]]; then
+ dokku_log_info1 "No matching app deploy found"
+ return
+ fi
+
+ PROCESS_GROUP_ID="$(ps -o pgid= "$PROCESS_ID" || true)"
+ if [[ -z "$PROCESS_ID" ]]; then
+ dokku_log_info1 "No matching app deploy found"
+ return
+ fi
+
+ dokku_log_info1 "Killing app deploy"
+ kill -quit -- "-${PROCESS_GROUP_ID}" && rm -f "$DOKKU_ROOT/$APP/.deploy.lock"
+}
+
+ps_kill_deploy_cmd "$@"

plugins/builds/subcommands/default

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_AVAILABLE_PATH/builds/internal-functions"
+
+cmd-builds-help "builds:help"

plugins/builds/subcommands/list

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+
+cmd-builds-list() {
+ declare desc="list all running builds"
+ declare cmd="builds:list"
+ [[ "$1" == "$cmd" ]] && shift 1
+
+}
+
+cmd-builds-list "$@"

plugins/builds/subcommands/output

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+
+cmd-builds-output() {
+ declare desc="shows build output"
+ declare cmd="builds:output"
+ [[ "$1" == "$cmd" ]] && shift 1
+ declare APP="$1"
+ verify_app_name "$APP"
+
+ local APP_DEPLOY_LOCK_FILE PROCESS_ID
+ APP_DEPLOY_LOCK_FILE="$DOKKU_ROOT/$APP/.deploy.lock"
+ if [[ ! -f "$APP_DEPLOY_LOCK_FILE" ]]; then
+ dokku_log_info1 "No matching app deploy found"
+ return
+ fi
+
+ PROCESS_ID="$(cat "$APP_DEPLOY_LOCK_FILE")"
+ if [[ -z "$PROCESS_ID" ]]; then
+ dokku_log_info1 "No matching app deploy found"
+ return
+ fi
+}
+
+cmd-builds-output "$@"

plugins/builds/subcommands/report

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+
+cmd-builds-report() {
+ declare desc="displays a build report for one or more apps"
+ declare cmd="builds:report"
+ [[ "$1" == "$cmd" ]] && shift 1
+ declare APP="$1"
+ verify_app_name "$APP"
+
+}
+
+cmd-builds-report "$@"

plugins/common/functions

@@ -972,6 +972,7 @@ acquire_advisory_lock() {
  dokku_log_fail "Run 'apps:unlock' to release the existing deploy lock"
  fi
  fi
+ echo "$DOKKU_PID" 1>&"$LOCK_FD"
 }
 
 release_advisory_lock() {