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

docs: refactor process docs

Browse Source 
- split out run and enter docs into two different sections
- gather all process related docs into one new section
- add scheduled cron task docs
This commit is contained in:
Jose Diaz-Gonzalez
2021-01-21 01:30:28 -05:00
parent 8efac2923b
commit 065bba5851
6 changed files with 187 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/processes/entering-containers.md Normal file
View File

@@ -0,0 +1,29 @@
# Entering containers
> New as of 0.4.0
```
enter <app> [<container-type> || --container-id <container-id>] # Connect to a specific app container
```
## Usage
The `enter` command can be used to enter a running container. The following variations of the command exist:
```shell
dokku enter node-js-app web
dokku enter node-js-app web.1
dokku enter node-js-app --container-id ID
```
Additionally, the `enter` command can be executed with no `<container-type>`. If only a single `<container-type>` is defined in the app's Procfile, executing `enter` will drop the terminal into the only running container. This behavior is not supported when specifying a custom command; as described below.
By default, it runs a `/bin/bash`, but can also be used to run a custom command:
```shell
# just echo hi
dokku enter node-js-app web echo hi
# run a long-running command, as one might for a cron task
dokku enter node-js-app web python script/background-worker.py
```

62
docs/processes/one-off-tasks.md Normal file
View File

@@ -0,0 +1,62 @@
# One-off Tasks
```
run [ --env KEY=VALUE | -e KEY=VALUE ] <app> <cmd> # Run a command in a new container using the current application image
```
Sometimes it is necessary to run a one-off command under an application. Dokku makes it easy to run a fresh container via the `run` command.
## Usage
The `run` command can be used to run a one-off process for a specific command. This will start a new container and run the desired command within that container. Note that this container will be stay around even after command completes. The container will be the same container as was used to start the currently deployed application.
```shell
# runs `ls -lah` in the `/app` directory of the application `node-js-app`
dokku run node-js-app ls -lah
# optionally, run can be passed custom environment variables
dokku run --env "NODE_ENV=development" --env "PATH=/custom/path" node-js-app npm run mytask
```
The `run` command can also be used to run a command defined in the app `Procfile`:
```
console: bundle exec racksh
```
```shell
# runs `bundle exec racksh` in the `/app` directory of the application `my-app`
dokku run my-app console
```
If the container running the command should be removed after exit, the `--rm-container` or `--rm` global flags can be specified to remove the containers automatically:
```shell
dokku --rm-container run node-js-app ls -lah
dokku --rm run node-js-app ls -lah
```
Alternatively, a global property can be set to always remove `run` containers.
```shell
# don't keep `run` containers around
dokku config:set --global DOKKU_RM_CONTAINER=1
# revert the above setting and keep containers around
dokku config:unset --global DOKKU_RM_CONTAINER
```
Containers may have specific labels attached. In order to avoid issues with dokku internals, do not use any labels beginning with either `com.dokku` or `org.label-schema`.
```shell
dokku --label=com.example.test-label=value run node-js-app ls -lah
```
Finally, a container can be run in "detached" mode via the `--detach` Dokku flag. Running a process in detached mode will immediately return a `CONTAINER_ID`. It is up to the user to then further manage this container in whatever manner they see fit, as Dokku will *not* automatically terminate the container.
```shell
dokku --detach run node-js-app ls -lah
# returns the ID of the new container
```
> Note that the `--rm-container` or `--rm` flags cannot be used when running containers in detached mode, and attempting to do so will result in the `--detach` flag being ignored.

297
docs/processes/process-management.md Normal file
View File

@@ -0,0 +1,297 @@
# Process and Container Management
> New as of 0.3.14, Enhanced in 0.7.0
```
ps:inspect <app> # Displays a sanitized version of docker inspect for an app
ps:rebuild [--parallel count] [--all|<app>] # Rebuilds an app from source
ps:report [<app>] [<flag>] # Displays a process report for one or more apps
ps:restart [--parallel count] [--all|<app>] # Restart an app
ps:restore [<app>] # Start previously running apps e.g. after reboot
ps:scale [--skip-deploy] <app> <proc>=<count> [<proc>=<count>...] # Get/Set how many instances of a given process to run
ps:set <app> <key> <value> # Set or clear a ps property for an app
ps:start [--parallel count] [--all|<app>] # Start an app
ps:stop [--parallel count] [--all|<app>] # Stop an app
```
## Usage
### Inspecting app containers
> New as of 0.13.0
A common administrative task to perform is calling `docker inspect` on the containers that are running for an app. This can be an error-prone task to perform, and may also reveal sensitive environment variables if not done correctly. Dokku provides a wrapper around this command via the `ps:inspect` command:
```shell
dokku ps:inspect node-js-app
```
This command will gather all the running container IDs for your app and call `docker inspect`, sanitizing the output data so it can be copy-pasted elsewhere safely.
### Rebuilding apps
> Warning: This section applies only to git-based deploys, and only works deterministically for these apps. Please see the [images documentation](/docs/deployment/methods/images.md) and [tar documentation](/docs/deployment/methods/tar.md)
> in for more information concerning rebuilding those apps.
It may be useful to rebuild an app at will, such as for commands that do not rebuild an app or when skipping a rebuild after setting multiple config values. For these use cases, the `ps:rebuild` function can be used.
```shell
dokku ps:rebuild node-js-app
```
All apps may be rebuilt by using the `--all` flag.
```shell
dokku ps:rebuild --all
```
By default, rebuilding all apps happens serially. The parallelism may be controlled by the `--parallel` flag.
```shell
dokku ps:rebuild --all --parallel 2
```
Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the `--parallel` flag to `-1`
```shell
dokku ps:rebuild --all --parallel -1
```
A missing linked container will result in failure to boot apps. Services should all be started for apps being rebuilt.
### Restarting apps
An app may be restarted using the `ps:restart` command.
```shell
dokku ps:restart node-js-app
```
All apps may be restarted by using the `--all` flag.
```shell
dokku ps:restart --all
```
By default, restarting all apps happens serially. The parallelism may be controlled by the `--parallel` flag.
```shell
dokku ps:restart --all --parallel 2
```
Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the `--parallel` flag to `-1`
```shell
dokku ps:restart --all --parallel -1
```
A missing linked container will result in failure to boot apps. Services should all be started for apps being rebuilt.
### Displaying existing scale properties
Issuing the `ps:scale` command with no arguments will output the current scaling properties for an app.
```shell
dokku ps:scale node-js-app
```
```
-----> Scaling for python
proctype: qty
--------: ---
web: 1
```
### Scaling apps
#### Via CLI
> This functionality is disabled if the formation is managed via a file such as `DOKKU_SCALE`.
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 `DOKKU_SCALE` formation file disables the ability to use `ps:scale` for scaling.
A `DOKKU_SCALE` 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/DOKKU_SCALE`
- Dockerfile: `WORKDIR/DOKKU_SCALE` or `/DOKKU_SCALE`
- Docker Image: `WORKDIR/DOKKU_SCALE` or `/DOKKU_SCALE`
The `DOKKU_SCALE` file format is as follows:
```Procfile
web=1
worker=2
```
Removing the file will result in Dokku respecting the `ps:scale` command for setting scale values.
#### 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 others - may be managed via `ps:scale` or a `DOKKU_SCALE` formation 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/configuration/nginx.md#request-proxying) for more information on how nginx handles proxied requests.
- Only the `web` process may be bound to an external port.
### 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.
```shell
dokku ps:stop node-js-app
```
All apps may be stopped by using the `--all` flag.
```shell
dokku ps:stop --all
```
By default, stopping all apps happens serially. The parallelism may be controlled by the `--parallel` flag.
```shell
dokku ps:stop --all --parallel 2
```
Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the `--parallel` flag to `-1`
```shell
dokku ps:stop --all --parallel -1
```
### Starting apps
All stopped containers can be started using the `ps:start` command. This is similar to running `ps:restart`, except no action will be taken if the app containers are running.
```shell
dokku ps:start node-js-app
```
All apps may be started by using the `--all` flag.
```shell
dokku ps:start --all
```
By default, starting all apps happens serially. The parallelism may be controlled by the `--parallel` flag.
```shell
dokku ps:start --all --parallel 2
```
Finally, the number of parallel workers may be automatically set to the number of CPUs available by setting the `--parallel` flag to `-1`
```shell
dokku ps:start --all --parallel -1
```
### Restart policies
> New as of 0.7.0, Command Changed in 0.22.0
By default, Dokku will automatically restart containers that exit with a non-zero status up to 10 times via the [on-failure Docker restart policy](https://docs.docker.com/engine/reference/run/#restart-policies---restart).
#### Setting the restart policy
> A change in the restart policy must be followed by a `ps:rebuild` call.
You can configure this via the `ps:set` command:
```shell
# always restart an exited container
dokku ps:set node-js-app restart-policy always
# never restart an exited container
dokku ps:set node-js-app restart-policy no
# only restart it on Docker restart if it was not manually stopped
dokku ps:set node-js-app restart-policy unless-stopped
# restart only on non-zero exit status
dokku ps:set node-js-app restart-policy on-failure
# restart only on non-zero exit status up to 20 times
dokku ps:set node-js-app restart-policy on-failure:20
```
Restart policies have no bearing on server reboot, and Dokku will always attempt to restart your apps at that point unless they were manually stopped.
### Displaying reports for an app
> New as of 0.12.0
You can get a report about the deployed apps using the `ps:report` command:
```shell
dokku ps:report
```
```
=====> node-js-app ps information
Deployed: false
Processes: 0
Ps can scale: true
Ps restart policy: on-failure:10
Restore: true
Running: false
=====> python-sample ps information
Deployed: false
Processes: 0
Ps can scale: true
Ps restart policy: on-failure:10
Restore: true
Running: false
=====> ruby-sample ps information
Deployed: false
Processes: 0
Ps can scale: true
Ps restart policy: on-failure:10
Restore: true
Running: false
```
You can run the command for a specific app also.
```shell
dokku ps:report node-js-app
```
```
=====> node-js-app ps information
Deployed: false
Processes: 0
Ps can scale: true
Ps restart policy: on-failure:10
Restore: true
Running: false
```
You can pass flags which will output only the value of the specific information you want. For example:
```shell
dokku ps:report node-js-app --deployed
```

194
docs/processes/scheduled-cron-tasks.md Normal file
View File

@@ -0,0 +1,194 @@
# Scheduled Cron T
asks
> New as of 0.23.0
```
cron:list <app> # List scheduled cron tasks for an app
cron:report [<app>] [<flag>] # Display report about an app
```
## Usage
### Dokku Managed Cron
Dokku automates scheduled `dokku run` commands via it's `app.json` cron integration.
#### Specifying commands
The `app.json` file for a given app can define a special `cron` key that contains a list of commands to run on given schedules. The following is a simple example `app.json` that simply runs the command `true` once a day:
```
{
"cron": [
{
"command": "true",
"schedule": "@daily"
}
]
}
```
A cron entry takes the following properties:
- `command`: A command to be run within the built app image. Specified commands can also be `Procfile` entries.
- `schedule`: A [cron-compatible](https://en.wikipedia.org/wiki/Cron#Overview) scheduling definition upon which to run the command. Seconds are generally not supported.
Zero or more cron commands can be specified per app. Cron entries are validated after the build artifact is created but before the app is deployed, and the cron schedule is updated during the post-deploy phase.
#### Task Environment
When running scheduled cron tasks, there are a few items to be aware of:
- Scheduled cron tasks are performed within the app environment available at runtime. If the app image does not exist, the command may fail to execute.
- Schedules are performed on the hosting server's timezone, which is typically UTC.
- At this time, only the `PATH` and `SHELL` environment variables are specified in the cron template.
- Each scheduled task is executed within a one-off `run` container, and thus inherit any docker-options specified for `run` containers.Resources are never shared between scheduled tasks.
- Tasks are always executed using the `--rm` flag, and are never executed in detached mode.
- Scheduled cron tasks are supported on a per-scheduler basis, and are currently only implemented by the `docker-local` scheduler.
- Tasks for _all_ apps managed by the `docker-local` scheduler are written to a single crontab file owned by the `dokku` user. The `dokku` user's crontab should be considered reserved for this purpose.
#### Listing Cron tasks
Cron tasks for an app can be listed via the `cron:list` command. This command takes an `app` argument.
```shell
dokku cron:list node-js-app
```
```
ID Schedule Command
cGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5 @daily node index.js
cGhwPT09dHJ1ZT09PSogKiAqICogKg== * * * * * true
```
#### Displaying reports for an app
You can get a report about the cron configuration for apps using the `cron:report` command:
```shell
dokku cron:report node-js-app
```
```
=====> node-js-app cron information
Cron task count: 2
=====> python-sample cron information
Cron task count: 0
=====> ruby-sample cron information
Cron task count: 10
```
You can run the command for a specific app also.
```shell
dokku cron:report node-js-app
```
```
=====> node-js-app cron information
Cron task count: 2
```
You can pass flags which will output only the value of the specific information you want. For example:
```shell
dokku cron:report node-js-app --cron-task-count
```
### Self Managed Cron
> Warning: Self-managed cron tasks should be considered advanced usage. While the instructions are available, users are highly encouraged to use the built-in scheduled cron task support unless absolutely necessary.
Some installations may require more fine-grained control over cron usage. The following are advanced instructions for configuring cron.
#### Using `run` for cron tasks
You can always use a one-off container to run an app task:
```shell
dokku --rm run node-js-app some-command
dokku --rm-container run node-js-app some-command
```
For tasks that should not be interrupted, run is the *preferred* method of handling cron tasks, as the container will continue running even during a deploy or scaling event. The trade-off is that there will be an increase in memory usage if there are multiple concurrent tasks running.
#### Using `enter` for cron tasks
Your Procfile can have the following entry:
```Procfile
cron: sleep infinity
```
With the `cron` process scaled to `1`:
```shell
dokku ps:scale node-js-app cron=1
```
You can now run all your commands in that container:
```shell
dokku enter node-js-app cron some-command
```
Note that you can also run multiple commands at the same time to reduce memory usage, though that may result in polluting the container environment.
For tasks that will properly resume, you *should* use the above method, as running tasks will be interrupted during deploys and scaling events, and subsequent commands will always run with the latest container. Note that if you scale the cron container down, this may interrupt proper running of the task.
#### General cron recommendations
Regularly scheduled tasks can be a bit of a pain with Dokku. The following are general recommendations to follow to help ensure successful task runs.
- Use the `dokku` user's crontab.
- If you do not, the `dokku` binary will attempt to execute with `sudo`, and your cron run with fail with `sudo: no tty present and no askpass program specified`.
- Add a `MAILTO` environment variable to ship cron emails to yourself.
- Add a `PATH` environment variable or specify the full path to binaries on the host.
- Add a `SHELL` environment variable to specify Bash when running commands.
- Keep your cron tasks in time-sorted order.
- Keep your server time in UTC so you don't need to translate daylight savings time when reading the cronfile.
- Run tasks at the lowest traffic times if possible.
- Use cron to *trigger* jobs, not run them. Use a real queuing system such as rabbitmq to actually process jobs.
- Try to keep tasks quiet so that mails only send on errors.
- Do not silence standard error or standard out. If you silence the former, you will miss failures. Silencing the latter means you should actually make app changes to handle log levels.
- Use a service such as [Dead Man's Snitch](https://deadmanssnitch.com) to verify that cron tasks completed successfully.
- Add lots of comments to your cronfile, including what a task is doing, so that you don't spend time deciphering the file later.
- Place your cronfiles in a pattern such as `/etc/cron.d/APP`.
- Do not use non-ASCII characters in your cronfile names. cron is finicky.
- Remember to have trailing newlines in your cronfile! cron is finicky.
The following is a sample cronfile that you can use for your apps:
```cron
# server cron jobs
MAILTO="mail@dokku.me"
PATH=/usr/local/bin:/usr/bin:/bin
SHELL=/bin/bash
# m h dom mon dow username command
# * * * * * dokku command to be executed
# - - - - -
# | | | | |
# | | | | +----- day of week (0 - 6) (Sunday=0)
# | | | +------- month (1 - 12)
# | | +--------- day of month (1 - 31)
# | +----------- hour (0 - 23)
# +----------- min (0 - 59)
### HIGH TRAFFIC TIME IS B/W 00:00 - 04:00 AND 14:00 - 23:59
### RUN YOUR TASKS FROM 04:00 - 14:00
### KEEP SORTED IN TIME ORDER
### PLACE ALL CRON TASKS BELOW
# removes unresponsive users from the subscriber list to decrease bounce rates
0 0 * * * dokku dokku --rm run node-js-app some-command
# sends out our email alerts to users
0 1 * * * dokku dokku ps:scale node-js-app cron=1 && dokku enter node-js-app cron some-other-command && dokku ps:scale node-js-app cron=0
### PLACE ALL CRON TASKS ABOVE, DO NOT REMOVE THE WHITESPACE AFTER THIS LINE
```