From f465c0e22179baf6b2939bf2a6e90ddbf0992340 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 1 Jul 2023 18:02:42 -0400 Subject: [PATCH] docs: unify all Procfile-handling documentation under the process management docs This makes it more clear as to how the various builders utilize the Procfile, and also ensures we don't have conflicting information anywhere. --- .../builders/cloud-native-buildpacks.md | 4 + docs/deployment/builders/dockerfiles.md | 23 +--- .../builders/herokuish-buildpacks.md | 29 +---- docs/deployment/schedulers/docker-local.md | 2 +- docs/processes/process-management.md | 111 ++++++++++++------ 5 files changed, 82 insertions(+), 87 deletions(-) diff --git a/docs/deployment/builders/cloud-native-buildpacks.md b/docs/deployment/builders/cloud-native-buildpacks.md index d4377b3dd..23d5c6ab9 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 7151cbc5f..12874f1b5 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 31b9976b6..947c36b97 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 c55ad1345..1d10bd7c3 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 eb8af7458..1527ccb29 100644 --- a/docs/processes/process-management.md +++ b/docs/processes/process-management.md @@ -105,6 +105,78 @@ proctype: qty web: 1 ``` +### Defining Processes + +#### Procfile + +> 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. + +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. + +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 +``` + +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. + +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 + +For initial app deploys, Dokku will default to starting a single `web` process for each app. This process may be defined within the `Procfile` or as the `CMD` (for Dockerfile or Docker image deploys). Scaling of the `web` process - and all other processes - may be managed via `ps:scale` or the `formation` key in the `app.json` file either before or after the initial deploy. + +There are also a few other exceptions for the `web` process. + +- Custom checks defined by a `CHECKS` file only apply to the `web` process type. +- By default, the built-in nginx proxy implementation only proxies the `web` process (others may be handled via a custom `nginx.conf.sigil`). + - 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`. + +For deploys via the `git:from-image` and `git:load-image` commands, the `Procfile` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `Procfile` extracted directly from the source code. Both cases will respect the configured `procfile-path` property value. + +```shell +dokku ps:set node-js-app procfile-path .dokku/Procfile +``` + +The default value may be set by passing an empty value for the option: + +```shell +dokku ps:set node-js-app procfile-path +``` + +The `procfile-path` property can also be set globally. The global default is `Procfile`, and the global value is used when no app-specific value is set. + +```shell +dokku ps:set --global procfile-path global-Procfile +``` + +The default value may be set by passing an empty value for the option. + +```shell +dokku ps:set --global procfile-path +``` + ### Scaling apps #### Via CLI @@ -152,45 +224,6 @@ Removing the `formation` key or removing the `app.json` file from your repositor 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 - -For initial app deploys, Dokku will default to starting a single `web` process for each app. This process may be defined within the `Procfile` or as the `CMD` (for Dockerfile or Docker image deploys). Scaling of the `web` process - and all other processes - may be managed via `ps:scale` or the `formation` key in the `app.json` file either before or after the initial deploy. - -There are also a few other exceptions for the `web` process. - -- Custom checks defined by a `CHECKS` file only apply to the `web` process type. -- By default, the built-in nginx proxy implementation only proxies the `web` process (others may be handled via a custom `nginx.conf.sigil`). - - 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. - -#### 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`. - -For deploys via the `git:from-image` and `git:load-image` commands, the `Procfile` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `Procfile` extracted directly from the source code. Both cases will respect the configured `procfile-path` property value. - -```shell -dokku ps:set node-js-app procfile-path .dokku/Procfile -``` - -The default value may be set by passing an empty value for the option: - -```shell -dokku ps:set node-js-app procfile-path -``` - -The `procfile-path` property can also be set globally. The global default is `Procfile`, and the global value is used when no app-specific value is set. - -```shell -dokku ps:set --global procfile-path global-Procfile -``` - -The default value may be set by passing an empty value for the option. - -```shell -dokku ps:set --global procfile-path -``` - ### 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.