feat: implement the scheduler plugin

This also performs a one-time migration of the DOKKU_SCHEDULER values the scheduler plugin properties.

Closes #4739

docs/appendices/0.26.0-migration-guide.md

@@ -0,0 +1,6 @@
+# 0.25.0 Migration Guide
+
+
+## Changes
+
+- The `scheduler` plugin now controls the scheduler in use for deploys. Apps will have their `DOKKU_SCHEDULER` environment variables migrated to the scheduler plugin, after which that value will be removed from said app. Please see the [scheduler documentation](/docs/deployment/schedulers/scheduler-management.md) for more information.

docs/deployment/schedulers/null.md

@@ -8,8 +8,8 @@ The `null` scheduler does nothing, and is useful for routing to services not man
 
 ### Detection
 
-This scheduler is _never_ auto-detected. The scheduler _must_  be specified via the `config:set` command:
+This scheduler is _never_ auto-detected. The scheduler _must_  be specified via the `scheduler:set` command:
 
 ```shell
-dokku config:set node-js-app DOCKER_SCHEDULER=null
+dokku scheduler:set node-js-app selected null
 ```

docs/deployment/schedulers/scheduler-management.md

@@ -0,0 +1,116 @@
+# Scheduler Management
+
+> New as of 0.26.0
+
+```
+scheduler:report [<app>] [<flag>]   # Displays a scheduler report for one or more apps
+scheduler:set <app> <key> (<value>) # Set or clear a scheduler property for an app
+```
+
+Schedulers are a way of customizing how an app image is deployed, and can be used to interact with non-local systems such as Kubernetes and Nomad.
+
+## Usage
+
+### Scheduler selection
+
+Dokku supports the following built-in schedulers:
+
+- `scheduler-docker-local`: Schedules apps against the local docker socket and runs containers directly on the Dokku host. See the [docker-local scheduler documentation](/docs/deployment/schedulers/docker-local.md) for more information on how this scheduler functions.
+- `scheduler-null`: Does nothing during the scheduler phase. See the [null scheduler documentation](/docs/deployment/schedulers/null.md) for more information on how this scheduler functions.
+
+See the [alternate schedulers documentation](/docs/deployment/schedulers/alternate-schedulers.md) for more information on other scheduler plugins.
+
+### Overriding the auto-selected scheduler
+
+If desired, the scheduler can be specified via the `scheduler:set` command by speifying a value for `selected`. The selected scheduler will always be used.
+
+```shell
+dokku scheduler:set node-js-app selected docker-local
+```
+
+The default value may be set by passing an empty value for the option:
+
+```shell
+dokku scheduler: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 scheduler:set --global selected docker-local
+```
+
+The default value may be set by passing an empty value for the option.
+
+```shell
+dokku scheduler:set --global selected
+```
+
+### Displaying scheduler reports for an app
+
+You can get a report about the app's scheduler status using the `scheduler:report` command:
+
+```shell
+dokku scheduler:report
+```
+
+```
+=====> node-js-app scheduler information
+       Scheduler computed selected:  herokuish
+       Scheduler global selected: herokuish
+       Scheduler selected: herokuish
+=====> python-sample scheduler information
+       Scheduler computed selected: dockerfile
+       Scheduler global selected: herokuish
+       Scheduler selected: dockerfile
+=====> ruby-sample scheduler information
+       Scheduler computed selected: herokuish
+       Scheduler global selected: herokuish
+       Scheduler selected:
+```
+
+You can run the command for a specific app also.
+
+```shell
+dokku scheduler:report node-js-app
+```
+
+```
+=====> node-js-app scheduler information
+       Scheduler selected: herokuish
+```
+
+You can pass flags which will output only the value of the specific information you want. For example:
+
+```shell
+dokku scheduler:report node-js-app --scheduler-selected
+```
+
+### Custom schedulers
+
+To create a custom scheduler, the following triggers may be implemented:
+
+- `check-deploy`
+- `core-post-deploy`
+- `post-app-clone-setup`
+- `post-app-rename-setup`
+- `post-create`
+- `post-delete`
+- `pre-deploy`
+- `pre-restore`
+- `scheduler-app-status`
+- `scheduler-deploy`
+- `scheduler-docker-cleanup`
+- `scheduler-inspect`
+- `scheduler-is-deployed`
+- `scheduler-logs`
+- `scheduler-logs-failed`
+- `scheduler-retire`
+- `scheduler-run`
+- `scheduler-stop`
+- `scheduler-tags-create`
+- `scheduler-tags-destroy`
+
+Custom plugins names _must_ have the prefix `scheduler-` or scheduler overriding via `scheduler:set` may not function as expected.
+
+Schedulers can use any tools available on the system to build the docker image, and may even be used to interact with off-server systems. The only current requirement is that the scheduler must have access to the image built in the build phase. If this is not the case, the registry plugin can be used to push the image to a registry that the scheduler software can access.

docs/development/plugin-triggers.md

@@ -2058,6 +2058,25 @@ DOKKU_SCHEDULER="$1"; APP="$2"; IMAGE_TAG="$3";
 # TODO
 ```
 
+### `scheduler-detect`
+
+> Warning: The scheduler plugin trigger apis are under development and may change
+> between minor releases until the 1.0 release.
+
+- Description: Allows you to check which scheduler is in use for an app
+- Invoked by: `dokku deploy`
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+APP="$1"
+
+# TODO
+```
+
 ### `scheduler-enter`
 
 > Warning: The scheduler plugin trigger apis are under development and may change

docs/getting-started/upgrading.md

@@ -19,6 +19,8 @@ Docker releases updates periodically to their engine. We recommend reading their
 
 Before upgrading, check the migration guides to get comfortable with new features and prepare your deployment to be upgraded.
 
+- [Upgrading to 0.26](/docs/appendices/0.26.0-migration-guide.md)
+- [Upgrading to 0.25](/docs/appendices/0.25.0-migration-guide.md)
 - [Upgrading to 0.24](/docs/appendices/0.24.0-migration-guide.md)
 - [Upgrading to 0.23](/docs/appendices/0.23.0-migration-guide.md)
 - [Upgrading to 0.22](/docs/appendices/0.22.0-migration-guide.md)

docs/networking/network.md

@@ -141,7 +141,7 @@ dokku apps:create local-app
 dokku builder:set local-app selected null
 
 # set the scheduler to the null scheduler, which does nothing
-dokku config:set local-app DOKKU_SCHEDULER=null
+dokku scheduler:set local-app selected null
 
 # set the static-web-listener network property to the ip:port combination for your app.
 dokku network:set local-app static-web-listener 127.0.0.1:8080

docs/template.html

@@ -160,8 +160,10 @@
 
             <a href="#" class="list-group-item disabled">Schedulers</a>
 
-            <a href="/{{NAME}}/advanced-usage/schedulers/docker-local/" class="list-group-item">Docker Local</a>
-            <a href="/{{NAME}}/advanced-usage/schedulers/alternate-schedulers/" class="list-group-item">Alternate Schedulers</a>
+            <a href="/{{NAME}}/deployment/schedulers/scheduler-management/" class="list-group-item">Scheduler Management</a>
+            <a href="/{{NAME}}/deployment/schedulers/docker-local/" class="list-group-item">Docker Local</a>
+            <a href="/{{NAME}}/deployment/schedulers/null/" class="list-group-item">Null Scheduler</a>
+            <a href="/{{NAME}}/deployment/schedulers/alternate-schedulers/" class="list-group-item">Alternate Schedulers</a>
 
             <a href="#" class="list-group-item disabled">Development</a>