dokku · josegonzalez · Mar 1, 2021 · Feb 4, 2021 · Feb 28, 2021 · Feb 28, 2021
diff --git a/docs/appendices/0.24.0-migration-guide.md b/docs/appendices/0.24.0-migration-guide.md
@@ -3,3 +3,8 @@
 ## Changes
 
 - The commands `proxy:enable`, `proxy:disable` and `proxy:build-config` now support the `--all` flag in addition to general parallelism.
+- The `builder-cnb` plugin has been renamed `builder-pack`, and all related plugin triggers have had the suffix `-cnb` changed to `-pack`.
+
+## Deprecations
+
+- The 1.0.0 release of Dokku will no longer select buildpack builders over dockerfile builders if both builders match. Instead, Dokku will choose the first builder that responds to the `builder-detect` trigger. Users that wish to use a specific builder may set a builder using the `builder:set` command, which will force Dokku to use the specified builder regardless of what might be auto-detected.
diff --git a/docs/deployment/builders/builder-management.md b/docs/deployment/builders/builder-management.md
@@ -0,0 +1,108 @@
+# Builder Management
+
+> New as of 0.24.0
+
+```
+builder:report [<app>] [<flag>]   # Displays a builder report for one or more apps
+builder:set <app> <key> (<value>) # Set or clear a builder property for an app
+```
+
+Builders are a way of customizing how an app is built from a source, allowing users flexibility in how artifacts are created for later scheduling.
+
+## Usage
+
+### Builder selection
+
+Dokku supports the following built-in builders:
+
+- `builder-dockerfile`: Builds apps using a `Dockerfile` via `docker build`. See the [dockerfile builder documentation](/docs/deployment/builders/dockerfiles.md) for more information on how this builder functions.
+- `builder-herokuish`: Builds apps with Heroku's v2a Buildpack specification via `gliderlabs/herokuish`. See the [herokuish builder documentation](/docs/deployment/builders/herokuish-buildpacks.md) for more information on how this builder functions.
+- `builder-pack`: Builds apps with Cloud Native Buildpacks via the `pack-cli`  tool. See the [cloud native buildpacks builder documentation](/docs/deployment/builders/cloud-native-buildpacks.md) for more information on how this builder functions.
+
+Builders run a detection script against a source code repository, and the first detected builder will be used to build the app artifact. The exception to this is when a `Dockerfile` is detected and the app is also able to use either `herokuish` or `pack-cli` for building, in which case one of the latter will be chosen.
+
+### Overriding the auto-selected builder
+
+If desired, the builder can be specified via the `builder:set` command by speifying a value for `selected`. The selected builder will always be used.
+
+```shell
+dokku builder:set node-js-app selected dockerfile
+```
+
+The default value may be set by passing an empty value for the option:
+
+```shell
+dokku builder:set node-js-app selected
+```
+
+The `selected` property can also be set globally. The global default is an empty string, and auto-detection will be performed when no value is set per-app or globally.
+
+```shell
+dokku builder:set --global selected herokuish
+```
+
+The default value may be set by passing an empty value for the option.
+
+```shell
+dokku builder:set --global selected
+```
+
+### Displaying builder reports for an app
+
+You can get a report about the app's builder status using the `builder:report` command:
+
+```shell
+dokku builder:report
+```
+
+```
+=====> node-js-app builder information
+       Builder computed selected: herokuish
+       Builder global selected: herokuish
+       Builder selected: herokuish
+=====> python-sample builder information
+       Builder computed selected: dockerfile
+       Builder global selected: herokuish
+       Builder selected: dockerfile
+=====> ruby-sample builder information
+       Builder computed selected: herokuish
+       Builder global selected: herokuish
+       Builder selected:
+```
+
+You can run the command for a specific app also.
+
+```shell
+dokku builder:report node-js-app
+```
+
+```
+=====> node-js-app builder information
+       Builder selected: herokuish
+```
+
+You can pass flags which will output only the value of the specific information you want. For example:
+
+```shell
+dokku builder:report node-js-app --builder-selected
+```
+
+### Custom builders
+
+To create a custom builder, the following triggers must be implemented:
+
+- `builder-build`:
+  - arguments: `BUILDER_TYPE` `APP` `SOURCECODE_WORK_DIR`
+  - description: Creates a docker image named with the output of `common#get_app_image_name $APP`.
+- `builder-detect`:
+  - arguments: `APP` `SOURCECODE_WORK_DIR`
+  - description: Outputs the name of the builder (without the `builder-` prefix) to use to build the app.
+- `builder-release`:
+  - arguments: `BUILDER_TYPE` `APP` `IMAGE_AG`
+  - description: A post-build, pre-release trigger that can be used to post-process the image. Usually simply tags and labels the image appropriately.
+
+Custom plugins names _must_ have the prefix `builder-` or builder overriding via `builder:set` may not function as expected.
+
+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.
diff --git a/...oyment/methods/cloud-native-buildpacks.md → ...yment/builders/cloud-native-buildpacks.md b/...oyment/methods/cloud-native-buildpacks.md → ...yment/builders/cloud-native-buildpacks.md
@@ -5,23 +5,39 @@
 ```
 buildpacks:set-property [--global|<app>] <key> <value>  # Set or clear a buildpacks property for an app
 ```
+
 Cloud Native Buildpacks are an evolution over the Buildpacks technology provided by the Herokuish builder. See the [herokuish buildpacks documentation](/docs/deployment/methods/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.
 
 ## Usage
 
-To use this builder instead of either `Dockerfile` or `herokuish`, you must set the `DOKKU_CNB_EXPERIMENTAL` environment variable for your app to `1`.
+### 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.
+
+The builder can also be specified via the `builder:set` command:
 
 ```shell
-dokku config:set --no-restart node-js-app DOKKU_CNB_EXPERIMENTAL=1
+dokku builder:set node-js-app selected pack
 ```
 
+> 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.
+
+### Requirements
+
 The `pack` cli tool is not included by default with Dokku or as a dependency. It must also be installed as shown on [this page](https://buildpacks.io/docs/tools/pack/).
 
 Builds will proceed with the `pack` cli for the app from then on.
 
-## Caveats
+### Caveats
 
 As this functionality is highly experimental, there are a number of caveats. Please note that not all issuesare listed below.
 

diff --git a/docs/deployment/methods/dockerfiles.md → docs/deployment/builders/dockerfiles.md b/docs/deployment/methods/dockerfiles.md → docs/deployment/builders/dockerfiles.md
@@ -6,20 +6,28 @@ While Dokku normally defaults to using [Heroku buildpacks](https://devcenter.her
 
 > Dockerfile support is considered a *power user* feature. By using Dockerfile-based deployment, you agree that you will not have the same comfort as that enjoyed by buildpack users, and Dokku features may work differently. Differences between the two systems will be documented here.
 
-To use a Dockerfile for deployment, commit a valid `Dockerfile` to the root of your repository and push the repository to your Dokku installation. If this file is detected, Dokku will default to using it to construct containers *except* in the following two cases:
+## Usage
 
-- The application has a `BUILDPACK_URL` environment variable set via the `dokku config:set` command or in a committed `.env` file. In this case, Dokku will use your specified buildpack.
-- The application has a `.buildpacks` file in the root of the repository. In this case, Dokku will use your specified buildpack(s).
+### Detection
 
-## Switching from buildpack deployments
+This builder will be auto-detected in the following case:
+
+- A `Dockerfile` exists in the root of the app repository.
+
+Dokku will only select the `dockerfile` builder if both the `herokuish` and `pack` builders are not detected and a Dockerfile exists. For more information on how those are detected, see the following links:
+
+- [Cloud Native Buildpacks documentation](/docs/deployment/builders/cloud-native-buildpacks.md#detection)
+- [Herokuish documentation](/docs/deployment/builders/herokuish-buildpacks.md#detection)
+
+### Switching from buildpack deployments
 
 If an application was previously deployed via buildpacks, the following commands should be run before a Dockerfile deploy will succeed:
 
 ```shell
 dokku config:unset --no-restart node-js-app DOKKU_PROXY_PORT_MAP 
 ```
 
-## Build-time configuration variables
+### Build-time configuration variables
 
 For security reasons - and as per [Docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available only during runtime.
 
@@ -65,11 +73,11 @@ ENV NODE_ENV ${NODE_ENV}
 RUN echo $NODE_ENV
 ```
 
-## Building images with Docker Buildkit
+### Building images with Docker Buildkit
 
 If your Dockerfile is using Docker engine's [buildkit](https://docs.docker.com/develop/develop-images/build_enhancements/) (not to be confused with buildpacks), then the `DOCKER_BUILDKIT=1` environment variable needs to be set. One way to do this is to edit `/etc/environment` on your dokku host and reboot your instance. Note, for complete build log output, you should also set `BUILDKIT_PROGRESS=plain` in the same file. 
 
-## Customizing the run command
+### 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`:
 
@@ -118,6 +126,6 @@ started by running `docker run bin/run-worker.sh` (the actual `docker run` comma
 complex, but this is the basic idea). If you use an `ENTRYPOINT` in your `Dockerfile`, the lines
 in your `Procfile` will be passed as arguments to the `ENTRYPOINT` script instead of being executed.
 
-## Exposed ports
+### 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.
diff --git a/...eployment/methods/herokuish-buildpacks.md → ...ployment/builders/herokuish-buildpacks.md b/...eployment/methods/herokuish-buildpacks.md → ...ployment/builders/herokuish-buildpacks.md
@@ -25,6 +25,23 @@ This page will cover usage of the `buildpacks` plugin.
 
 ## Usage
 
+### Detection
+
+This builder will be auto-detected in either the following cases:
+
+- The `BUILDPACK_URL` app environment variable is set.
+  - This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details.
+- A `.buildpacks` file exists in the root of the app repository.
+  - This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands.
+
+The builder can also be specified via the `builder:set` command:
+
+```shell
+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.

diff --git a/docs/development/plugin-triggers.md b/docs/development/plugin-triggers.md
@@ -143,6 +143,24 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `builder-detect`
+
+- Description: Allows overriding the auto-detected `herokuish` builder in favor of a custom one. Dockerfile gets lowest builder precedence.
+- Invoked by: `dokku deploy`
+- Arguments: `$APP` `$SOURCECODE_WORK_DIR`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+APP="$1"; SOURCECODE_WORK_DIR="$2"
+
+if [[ -f "$SOURCECODE_WORK_DIR/project.toml" ]]; then
+  echo -n "pack"
+fi
+```
+
 ### `builder-create-dokku-image`
 
 - Description: Allows modification of the configured dokku-image
@@ -1075,12 +1093,12 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
-### `post-build-cnb`
+### `post-build-pack`
 
-> Warning: The cnb plugin trigger apis are under development and may change
+> Warning: The pack plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
-- Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using cnb.
+- Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using pack.
 - Invoked by: `internal function dokku_build() (build phase)`
 - Arguments: `$APP` `$SOURCECODE_WORK_DIR`
 - Example:
@@ -1308,14 +1326,14 @@ APP="$1"; IMAGE_TAG="$2"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)
 # TODO
 ```
 
-### `post-release-cnb`
+### `post-release-pack`
 
-> Warning: The cnb plugin trigger apis are under development and may change
+> Warning: The pack plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 > Warning: Image mutation in this trigger may result in an invalid run state, and is heavily discouraged.
 
-- Description: Allows you to run commands after environment variables are set for the release step of the deploy. Only applies to apps using cnb.
+- Description: Allows you to run commands after environment variables are set for the release step of the deploy. Only applies to apps using pack.
 - Invoked by: `internal function dokku_release() (release phase)`
 - Arguments: `$APP $IMAGE_TAG`
 - Example:
@@ -1382,12 +1400,12 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
-### `pre-build-cnb`
+### `pre-build-pack`
 
-> Warning: The cnb plugin trigger apis are under development and may change
+> Warning: The pack plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
-- Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using cnb.
+- Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using pack.
 - Invoked by: `internal function dokku_build() (build phase)`
 - Arguments: `$APP` `$SOURCECODE_WORK_DIR`
 - Example:
@@ -1539,12 +1557,12 @@ docker commit "${DOCKER_COMMIT_LABEL_ARGS[@]}" $CID $IMAGE >/dev/null
 ```
 
 
-### `pre-release-cnb`
+### `pre-release-pack`
 
-> Warning: The cnb plugin trigger apis are under development and may change
+> Warning: The pack plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
-- Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using cnb.
+- Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using pack.
 - Invoked by: `internal function dokku_release() (release phase)`
 - Arguments: `$APP $IMAGE_TAG`
 - Example:

diff --git a/docs/template.html b/docs/template.html
@@ -127,11 +127,14 @@ <h1 class="heading navbar-brand">
             <a href="/{{NAME}}/deployment/user-management/" class="list-group-item">User Management</a>
             <a href="/{{NAME}}/deployment/zero-downtime-deploys/" class="list-group-item">Zero Downtime Deploy Checks</a>
 
-            <a href="#" class="list-group-item disabled">Deployment Methods</a>
+            <a href="#" class="list-group-item disabled">Builders</a>
+
+            <a href="/{{NAME}}/deployment/builders/builder-management/" class="list-group-item">Builder Management</a>
+            <a href="/{{NAME}}/deployment/builders/cloud-native-buildpacks/" class="list-group-item">Cloud Native Buildpacks</a>
+            <a href="/{{NAME}}/deployment/builders/herokuish-buildpacks/" class="list-group-item">Herokuish Buildpacks</a>
+            <a href="/{{NAME}}/deployment/builders/dockerfiles/" class="list-group-item">Dockerfile Deployment</a>
 
-            <a href="/{{NAME}}/deployment/methods/cloud-native-buildpacks/" class="list-group-item">Cloud Native Buildpacks</a>
-            <a href="/{{NAME}}/deployment/methods/herokuish-buildpacks/" class="list-group-item">Herokuish Buildpacks</a>
-            <a href="/{{NAME}}/deployment/methods/dockerfiles/" class="list-group-item">Dockerfile Deployment</a>
+            <a href="#" class="list-group-item disabled">Deployment Methods</a>
             <a href="/{{NAME}}/deployment/methods/images/" class="list-group-item">Docker Image Deployment</a>
             <a href="/{{NAME}}/deployment/methods/git/" class="list-group-item">Git Deployment</a>
             <a href="/{{NAME}}/deployment/methods/tar/" class="list-group-item">Tarfile Deployment</a>

diff --git a/docs/viewdocs.json b/docs/viewdocs.json
@@ -13,9 +13,14 @@
     "deployment/process-management": "processes/process-management/",
     "deployment/one-off-processes": "processes/one-off-tasks/",
 
-    "deployment/buildpacks": "deployment/methods/herokuish-buildpacks/",
-    "deployment/methods/buildpacks": "deployment/methods/herokuish-buildpacks/",
-    "deployment/dockerfiles": "deployment/methods/dockerfiles/",
+    "deployment/buildpacks": "deployment/builders/herokuish-buildpacks/",
+    "deployment/methods/buildpacks": "deployment/builders/herokuish-buildpacks/",
+    "deployment/dockerfiles": "deployment/builders/dockerfiles/",
+
+    "deployment/methods/cloud-native-buildpacks": "deployment/builders/cloud-native-buildpacks/",
+    "deployment/methods/dockerfiles": "deployment/builders/dockerfiles/",
+    "deployment/methods/herokuish-buildpacks": "deployment/builders/herokuish-buildpacks/",
+
     "deployment/images": "deployment/methods/images/",
     "configuration-management": "configuration/environment-variables/",
     "deployment/ssl-configuration": "configuration/ssl/",

diff --git a/plugins/20_events/builder-detect b/plugins/20_events/builder-detect
@@ -0,0 +1 @@
+hook
diff --git a/plugins/app-json/functions.go b/plugins/app-json/functions.go
@@ -188,7 +188,7 @@ func executeScript(appName string, image string, imageTag string, phase string)
 	if isHerokuishImage {
 		imageSourceType = "herokuish"
 	} else if isCnbImage {
-		imageSourceType = "cnb"
+		imageSourceType = "pack"
 	}
 
 	cacheDir := fmt.Sprintf("%s/cache", common.AppRoot(appName))

diff --git a/plugins/builder-cnb/plugin.toml b/plugins/builder-cnb/plugin.toml