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.

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