feat: add ability to increase the max parallelism when deploying a given process type

docs/deployment/schedulers/docker-local.md

@@ -37,9 +37,9 @@ Once set, you may re-enable it by setting a blank value for `disable-chown`:
 dokku scheduler-docker-local:set node-js-app disable-chown
 ```
 
-### Deploying Process Types in parallel
+### Deploying Process Types in Parallel
 
-> New as of 25.5
+> New as of 0.25.5
 
 By default, Dokku deploys an app's processes one-by-one in order, with the `web` process being deployed first. Deployment parallelism may be achieved by setting the `parallel-schedule-count` property, which defaults to `1`. Increasing this number increases the number of process types that may be deployed in parallel (with the web process being the exception).
 
@@ -60,6 +60,37 @@ Container scheduling output is shown in the order it is received, and thus may b
 
 Note that increasing the value of `parallel-schedule-count` may significantly impact CPU utilization on your host as your app containers - and their respective processes - start up. Setting a value higher than the number of available CPUs is discouraged. It is recommended that users carefully set this value so as not to overburden their server.
 
+#### Increasing parallelism within a process deploy
+
+> New as of 0.26.0
+
+By default, Dokku will deploy one instance of a given process type at a time. This can be increased by customizing the `app.json` `formation` key to include a `max_parallel` key for the given process type.
+
+An `app.json` file can be committed to the root of the pushed app repository, and must be within the built image artifact in the image's working directory as shown below.
+
+- Buildpacks: `/app/app.json`
+- Dockerfile: `WORKDIR/app.json` or `/app.json` (if no working directory specified)
+- Docker Image: `WORKDIR/app.json` or `/app.json` (if no working directory specified)
+
+The `formation` key should be specified as follows in the `app.json` file:
+
+```Procfile
+{
+  "formation": {
+    "web": {
+      "max_parallel": 1
+    },
+    "worker": {
+      "max_parallel": 4
+    }
+  }
+}
+```
+
+Omitting or removing the entry will result in parallelism for that process type to return to 1 entry at a time. This can be combined with the  `parallel-schedule-count` property to speed up deployments.
+
+Note that increasing the value of `max_parallel` may significantly impact CPU utilization on your host as your app containers - and their respective processes - start up. Setting a value higher than the number of available CPUs is discouraged. It is recommended that users carefully set this value so as not to overburden their server.
+
 ## Implemented Triggers
 
 This plugin implements various functionality through `plugn` triggers to integrate with Docker for running apps on a single server. The following functionality is supported by the `scheduler-docker-local` plugin.

docs/development/plugin-triggers.md

@@ -74,6 +74,21 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `app-json-process-deploy-parallelism`
+
+- Description: Decides the parallelism to use when deploying a given process type. The default is 1 process entry at a type.
+- Invoked by: `dokku deploy`
+- Arguments: `$APP $PROCESS_TYPE`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `app-maybe-create`
 
 - Description: Creates an app (gated by whether this is globally enabled or not)
@@ -962,7 +977,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 - Description: Return the port for a given app container
 - Invoked by: `internally triggered by a deploy`
-- Arguments: `$APP $PROC_TYPE $CONTAINER_ID $IS_HEROKUISH_CONTAINER`
+- Arguments: `$APP $PROCESS_TYPE $CONTAINER_ID $IS_HEROKUISH_CONTAINER`
 - Example:
 
 ```shell

docs/processes/process-management.md

@@ -131,7 +131,7 @@ dokku ps:scale --skip-deploy node-js-app web=1
 
 #### Manually managing process scaling
 
-> Using a `formation` key in an `app.json` file disables the ability to use `ps:scale` for scaling.
+> Using a `formation` key in an `app.json` file with _any_ `quantity` specified disables the ability to use `ps:scale` for scaling.
 
 An `app.json` file can be committed to the root of the pushed app repository, and must be within the built image artifact in the image's working directory as shown below.