docs: refactor process docs
- 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
29
docs/processes/entering-containers.md
Normal file
29
docs/processes/entering-containers.md
Normal 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
62
docs/processes/one-off-tasks.md
Normal 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.
|
||||
@@ -1,69 +1,110 @@
|
||||
# One-off Processes and Cron
|
||||
# Scheduled Cron T
|
||||
asks
|
||||
|
||||
Sometimes you need to either inspect running containers or run a one-off command under an application. In those cases, Dokku makes it easy to either connect to a running container or run a fresh container.
|
||||
|
||||
## Run a command in an app environment
|
||||
> New as of 0.23.0
|
||||
|
||||
```
|
||||
run [ --env KEY=VALUE | -e KEY=VALUE ] <app> <cmd> # Run a command in a new container using the current application image
|
||||
cron:list <app> # List scheduled cron tasks for an app
|
||||
cron:report [<app>] [<flag>] # Display report about an app
|
||||
```
|
||||
|
||||
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.
|
||||
## 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
|
||||
# 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
|
||||
dokku cron:list node-js-app
|
||||
```
|
||||
|
||||
The `run` command can also be used to run a command defined in your Procfile:
|
||||
```
|
||||
ID Schedule Command
|
||||
cGhwPT09cGhwIHRlc3QucGhwPT09QGRhaWx5 @daily node index.js
|
||||
cGhwPT09dHJ1ZT09PSogKiAqICogKg== * * * * * true
|
||||
```
|
||||
|
||||
```
|
||||
console: bundle exec racksh
|
||||
```
|
||||
#### Displaying reports for an app
|
||||
|
||||
You can get a report about the cron configuration for apps using the `cron:report` command:
|
||||
|
||||
```shell
|
||||
# runs `bundle exec racksh` in the `/app` directory of the application `my-app`
|
||||
dokku run my-app console
|
||||
dokku cron:report node-js-app
|
||||
```
|
||||
|
||||
If you want to remove the container after a command has started, you can run the following command:
|
||||
```
|
||||
=====> 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
|
||||
# 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
|
||||
dokku cron:report node-js-app
|
||||
```
|
||||
|
||||
You may also use the `--rm-container` or `--rm` Dokku flags to remove the containers automatically:
|
||||
```
|
||||
=====> 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 --rm-container run node-js-app ls -lah
|
||||
dokku --rm run node-js-app ls -lah
|
||||
dokku cron:report node-js-app --cron-task-count
|
||||
```
|
||||
|
||||
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`.
|
||||
### Self Managed Cron
|
||||
|
||||
```shell
|
||||
dokku --label=com.example.test-label=value run node-js-app ls -lah
|
||||
```
|
||||
> 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.
|
||||
|
||||
Finally, you may wish to run a container 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.
|
||||
Some installations may require more fine-grained control over cron usage. The following are advanced instructions for configuring cron.
|
||||
|
||||
```shell
|
||||
dokku --detach run node-js-app ls -lah
|
||||
# returns the ID of the new container
|
||||
```
|
||||
#### Using `run` for cron tasks
|
||||
|
||||
> Note that you may not use the `--rm-container` or `--rm` flags when running containers in detached mode, and attempting to do so will result in the `--detach` flag being ignored.
|
||||
|
||||
### Using `run` for cron tasks
|
||||
|
||||
You can always use a one-off container to run an application task:
|
||||
You can always use a one-off container to run an app task:
|
||||
|
||||
```shell
|
||||
dokku --rm run node-js-app some-command
|
||||
@@ -72,35 +113,8 @@ 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.
|
||||
|
||||
## Entering existing containers
|
||||
|
||||
> New as of 0.4.0
|
||||
|
||||
```
|
||||
enter <app> [<container-type> || --container-id <container-id>] # Connect to a specific app container
|
||||
```
|
||||
|
||||
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, you can run `enter` with no `<container-type>`. If only a single `<container-type>` is defined in your app, you will be dropped 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
|
||||
```
|
||||
|
||||
### Using `enter` for cron tasks
|
||||
#### Using `enter` for cron tasks
|
||||
|
||||
Your Procfile can have the following entry:
|
||||
|
||||
@@ -124,7 +138,7 @@ Note that you can also run multiple commands at the same time to reduce memory u
|
||||
|
||||
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
|
||||
#### 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.
|
||||
|
||||
@@ -138,14 +152,14 @@ Regularly scheduled tasks can be a bit of a pain with Dokku. The following are g
|
||||
- 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 application changes to handle log levels.
|
||||
- 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 applications:
|
||||
The following is a sample cronfile that you can use for your apps:
|
||||
|
||||
```cron
|
||||
# server cron jobs
|
||||
@@ -124,8 +124,6 @@
|
||||
<a href="/{{NAME}}/deployment/application-management/" class="list-group-item">Application Management</a>
|
||||
<a href="/{{NAME}}/deployment/logs/" class="list-group-item">Application Logs</a>
|
||||
<a href="/{{NAME}}/deployment/remote-commands/" class="list-group-item">Remote Commands</a>
|
||||
<a href="/{{NAME}}/deployment/one-off-processes/" class="list-group-item">One-Off Processes/Cron</a>
|
||||
<a href="/{{NAME}}/deployment/process-management/" class="list-group-item">Process Scaling</a>
|
||||
<a href="/{{NAME}}/deployment/user-management/" class="list-group-item">User Management</a>
|
||||
<a href="/{{NAME}}/deployment/zero-downtime-deploys/" class="list-group-item">Zero Downtime Deploy Checks</a>
|
||||
|
||||
@@ -145,6 +143,13 @@
|
||||
<a href="/{{NAME}}/configuration/nginx/" class="list-group-item">Nginx Configuration</a>
|
||||
<a href="/{{NAME}}/configuration/ssl/" class="list-group-item">SSL Configuration</a>
|
||||
|
||||
<a href="#" class="list-group-item disabled">Process Management</a>
|
||||
|
||||
<a href="/{{NAME}}/processes/entering-containers/" class="list-group-item">Entering Containers</a>
|
||||
<a href="/{{NAME}}/processes/one-off-tasks/" class="list-group-item">One-Off Tasks</a>
|
||||
<a href="/{{NAME}}/processes/process-management/" class="list-group-item">Process Scaling</a>
|
||||
<a href="/{{NAME}}/processes/scheduled-cron-tasks/" class="list-group-item">Scheduled Cron Tasks</a>
|
||||
|
||||
<a href="#" class="list-group-item disabled">Network Management</a>
|
||||
|
||||
<a href="/{{NAME}}/networking/dns/" class="list-group-item">DNS Configuration</a>
|
||||
|
||||
@@ -7,9 +7,12 @@
|
||||
|
||||
"application-deployment": "deployment/application-deployment/",
|
||||
"checks-examples": "deployment/zero-downtime-deploys/",
|
||||
"process-management": "deployment/process-management/",
|
||||
"remote-commands": "deployment/remote-commands/",
|
||||
|
||||
"process-management": "processes/process-management/",
|
||||
"deployment/process-management/": "processes/process-management/",
|
||||
"deployment/one-off-processes": "processes/deployment/one-off-tasks/",
|
||||
|
||||
"deployment/buildpacks": "deployment/methods/herokuish-buildpacks/",
|
||||
"deployment/methods/buildpacks": "deployment/methods/herokuish-buildpacks/",
|
||||
"deployment/dockerfiles": "deployment/methods/dockerfiles/",
|
||||
|
||||
Reference in New Issue
Block a user