diff --git a/docs/deployment/builders/cloud-native-buildpacks.md b/docs/deployment/builders/cloud-native-buildpacks.md index d4377b3dd44..23d5c6ab9a6 100644 --- a/docs/deployment/builders/cloud-native-buildpacks.md +++ b/docs/deployment/builders/cloud-native-buildpacks.md @@ -159,3 +159,7 @@ dokku buildpacks:set-property --global stack paketobuildpacks/build:base-cnb # unset globally dokku buildpacks:set-property --global stack ``` + +### Specifying commands via Procfile + +See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app. diff --git a/docs/deployment/builders/dockerfiles.md b/docs/deployment/builders/dockerfiles.md index 7151cbc5f56..12874f1b5a9 100644 --- a/docs/deployment/builders/dockerfiles.md +++ b/docs/deployment/builders/dockerfiles.md @@ -198,28 +198,7 @@ Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disa > New as of 0.5.0 -You can also customize the run command using a `Procfile`, much like you would on Heroku or -with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types). The commands in your app's Procfile will be passed to `docker run` to start your process(es). Here's an example `Procfile`: - -```Procfile -web: bin/run-prod.sh -worker: bin/run-worker.sh -``` - -And `Dockerfile`: - -```Dockerfile -FROM ubuntu:20.04 -WORKDIR /app -COPY . ./ -CMD ["bin/run-dev.sh"] -``` - -When the above example is deployed, the `web` process is started, with the command `bin/run-prod.sh` executed in the container. All other processes must be scaled up separately. If the app's `Dockerfile` contains an `ENTRYPOINT` directive, the command specified in the `Procfile` will be passed to that entrypoint script as an argument. - -See the [scaling apps documentation](/docs/processes/process-management.md#scaling-apps) for more information on how process scaling is performed. - -See the [app.json location documentation](/docs/processes/process-management.md#changing-the-procfile-location) for more information on where to place your `Procfile` file. +See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app. ### Exposed ports diff --git a/docs/deployment/builders/herokuish-buildpacks.md b/docs/deployment/builders/herokuish-buildpacks.md index 31b9976b6a3..947c36b9719 100644 --- a/docs/deployment/builders/herokuish-buildpacks.md +++ b/docs/deployment/builders/herokuish-buildpacks.md @@ -322,31 +322,6 @@ This will use the latest commit on the `master` branch of the specified buildpac dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs#v87 ``` -### Specifying commands via Procfile - -While many buildpacks have a default command that is run when a detected repository is pushed, it is possible to override this command via a Procfile. A Procfile can also be used to specify multiple commands, each of which is subject to process scaling. See the [process scaling documentation](/docs/processes/process-management.md) for more details around scaling individual processes. - -A Procfile is a file named `Procfile`. It should be named `Procfile` exactly, and not anything else. For example, `Procfile.txt` is not valid. The file should be a simple text file. - -The file must be placed in the root directory of your application. It will not function if placed in a subdirectory. - -If the file exists, it should not be empty, as doing so may result in a failed deploy. - -The syntax for declaring a `Procfile` is as follows. Note that the format is one process type per line, with no duplicate process types. - -``` -: -``` - -If, for example, you have multiple queue workers and wish to scale them separately, the following would be a valid way to work around the requirement of not duplicating process types: - -```Procfile -worker: env QUEUE=* bundle exec rake resque:work -importantworker: env QUEUE=important bundle exec rake resque:work -``` - -The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/docs/processes/process-management.md) for more details around scaling individual processes. - ### `curl` build timeouts Certain buildpacks may time out in retrieving dependencies via `curl`. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to `gzip: stdin: unexpected end of file` after a `curl` command. @@ -361,3 +336,7 @@ dokku config:set --global CURL_CONNECT_TIMEOUT=180 ### Clearing buildpack cache See the [repository management documentation](/docs/advanced-usage/repository-management.md#clearing-app-cache) for more information on how to clear buildpack build cache for an application. + +### Specifying commands via Procfile + +See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app. diff --git a/docs/deployment/schedulers/docker-local.md b/docs/deployment/schedulers/docker-local.md index c55ad134515..1d10bd7c33e 100644 --- a/docs/deployment/schedulers/docker-local.md +++ b/docs/deployment/schedulers/docker-local.md @@ -84,7 +84,7 @@ By default, Dokku will deploy one instance of a given process type at a time. Th The `formation` key should be specified as follows in the `app.json` file: -```Procfile +```json { "formation": { "web": { diff --git a/docs/processes/process-management.md b/docs/processes/process-management.md index eb8af745847..1527ccb2986 100644 --- a/docs/processes/process-management.md +++ b/docs/processes/process-management.md @@ -105,52 +105,34 @@ proctype: qty web: 1 ``` -### Scaling apps +### Defining Processes -#### Via CLI +#### Procfile -> This functionality is disabled if the formation is managed via the `formation` key of `app.json`. +> Note: Dokku supports the Procfile format as defined in [this document](https://github.com/dokku/procfile-util/blob/master/PROCFILE_FORMAT.md) under "Strict Mode" parsing rules. -Dokku can also manage scaling itself via the `ps:scale` command. This command can be used to scale multiple process types at the same time. +Apps can define processes to run by using a `Procfile`. A `Procfile` is a simple text file that can be used to specify multiple commands, each of which is subject to process scaling. In the case where the built image sets a default command to run - either through usage of `CMD` for Dockerfile-based builds, a default process for buildpack-based builds, or any other method for the builder in use - the `Procfile` will take precedence. -```shell -dokku ps:scale node-js-app web=1 -``` +If the file exists, it should not be empty, as doing so may result in a failed deploy. -Multiple process types can be scaled at once: +The syntax for declaring a `Procfile` is as follows. Note that the format is one process type per line, with no duplicate process types. -```shell -dokku ps:scale node-js-app web=1 worker=1 ``` - -If desired, the corresponding deploy will be skipped by using the `--skip-deploy` flag: - -```shell -dokku ps:scale --skip-deploy node-js-app web=1 +: ``` -#### Manually managing process scaling - -> Using a `formation` key in an `app.json` file with _any_ `quantity` specified disables the ability to use `ps:scale` for scaling. All processes not specified in the `app.json` will have their process count set to zero. - -Users can also configure scaling within the codebase itself to manage process scaling. The `formation` key should be specified as follows in the `app.json` file: +If, for example, you have multiple queue workers and wish to scale them separately, the following would be a valid way to work around the requirement of not duplicating process types: ```Procfile -{ - "formation": { - "web": { - "quantity": 1 - }, - "worker": { - "quantity": 4 - } - } -} +worker: env QUEUE=* bundle exec rake resque:work +importantworker: env QUEUE=important bundle exec rake resque:work ``` -Removing the `formation` key or removing the `app.json` file from your repository will result in Dokku respecting the `ps:scale` command for setting scale values. The values set via the `app.json` file from a previous deploy will be respected. +If the app build declares an `ENTRYPOINT`, the command defined in the `Procfile` is passed as an argument to that entrypoint. This is the case for all Dockerfile-based, Docker Image, and Cloud Native Buildpack deployments. -See the [app.json location documentation](/docs/advanced-usage/deployment-tasks.md#changing-the-appjson-location) for more information on where to place your `app.json` file. +The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [web process scaling documentation](/docs/processes/process-management.md#the-web-process) for more details around scaling individual processes. + +See the [Procfile location documentation](/docs/processes/process-management.md#changing-the-procfile-location) for more information on where to place your `Procfile` file. #### The `web` process @@ -163,6 +145,10 @@ There are also a few other exceptions for the `web` process. - See the [nginx request proxying documentation](/docs/networking/proxies/nginx.md#request-proxying) for more information on how nginx handles proxied requests. - Only the `web` process may be bound to an external port. +#### The `release` process + +The `Procfile` also supports a special `release` command which acts in a similar way to the [Heroku Release Phase](https://devcenter.heroku.com/articles/release-phase). See the [Release deployment task documentation](/docs/advanced-usage/deployment-tasks.md#procfile-release-command) for more information on how Dokku handles this process type. + #### Changing the `Procfile` location When deploying a monorepo, it may be desirable to specify the specific path of the `Procfile` file to use for a given app. This can be done via the `ps:set` command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no `Procfile`. @@ -191,6 +177,53 @@ The default value may be set by passing an empty value for the option. dokku ps:set --global procfile-path ``` +### Scaling apps + +#### Via CLI + +> This functionality is disabled if the formation is managed via the `formation` key of `app.json`. + +Dokku can also manage scaling itself via the `ps:scale` command. This command can be used to scale multiple process types at the same time. + +```shell +dokku ps:scale node-js-app web=1 +``` + +Multiple process types can be scaled at once: + +```shell +dokku ps:scale node-js-app web=1 worker=1 +``` + +If desired, the corresponding deploy will be skipped by using the `--skip-deploy` flag: + +```shell +dokku ps:scale --skip-deploy node-js-app web=1 +``` + +#### Manually managing process scaling + +> Using a `formation` key in an `app.json` file with _any_ `quantity` specified disables the ability to use `ps:scale` for scaling. All processes not specified in the `app.json` will have their process count set to zero. + +Users can also configure scaling within the codebase itself to manage process scaling. The `formation` key should be specified as follows in the `app.json` file: + +```Procfile +{ + "formation": { + "web": { + "quantity": 1 + }, + "worker": { + "quantity": 4 + } + } +} +``` + +Removing the `formation` key or removing the `app.json` file from your repository will result in Dokku respecting the `ps:scale` command for setting scale values. The values set via the `app.json` file from a previous deploy will be respected. + +See the [app.json location documentation](/docs/advanced-usage/deployment-tasks.md#changing-the-appjson-location) for more information on where to place your `app.json` file. + ### Stopping apps Deployed apps can be stopped using the `ps:stop` command. This turns off all running containers for an app, and will result in a **502 Bad Gateway** response for the default nginx proxy implementation.