github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merge pull request #5984 from dokku/procfile-format

Browse Source 
Unify all Procfile-handling documentation under the process management docs
This commit is contained in:
Jose Diaz-Gonzalez
2023-07-01 18:03:25 -04:00
committed by GitHub
parent 2f0d6c606f f465c0e221
commit 841856f7c7
5 changed files with 82 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/deployment/builders/cloud-native-buildpacks.md
View File

@@ -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.

23
docs/deployment/builders/dockerfiles.md
View File

@@ -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

29
docs/deployment/builders/herokuish-buildpacks.md
View File

@@ -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.
```
<process type>: <command>
```
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.

2
docs/deployment/schedulers/docker-local.md
View File

@@ -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": {

111
docs/processes/process-management.md
View File

@@ -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.
```
<process type>: <command>
```
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.