Merge pull request #8112 from dokku/7938-run-retire

Implement cron and one-off run task TTLs

docs/development/plugin-triggers.md

@@ -2805,6 +2805,26 @@ DOKKU_SCHEDULER="$1"; APP="$2"; CONTAINER="$3"; TAIL="$4"; PRETTY_PRINT="$5"; NU
 # TODO
 ```
 
+### `scheduler-run-retire`
+
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
+> between minor releases until the 1.0 release.
+
+- Description: Allows you to retire containers started by the `run` command
+- Invoked by: `dokku run:retire`
+- Arguments: `$DOKKU_SCHEDULER $APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+DOKKU_SCHEDULER="$1"; APP="$2";
+
+# TODO
+```
+
 ### `scheduler-run-stop`
 
 > [!WARNING]

docs/processes/one-off-tasks.md

@@ -1,8 +1,8 @@
 # One-off Tasks
 
 ```
-run [-e|--env KEY=VALUE] [--no-tty] <app> <cmd>              # Run a command in a new container using the current app image
-run:detached [-e|-env KEY=VALUE] [--force-tty] <app> <cmd>         # Run a command in a new detached container using the current app image
+run [-e|--env KEY=VALUE] [--no-tty] [--ttl-seconds SECONDS] <app> <cmd>              # Run a command in a new container using the current app image
+run:detached [-e|-env KEY=VALUE] [--force-tty] [--ttl-seconds SECONDS] <app> <cmd>         # Run a command in a new detached container using the current app image
 run:list [--format json|stdout] [<app>]                      # List all run containers for an app
 run:logs <app|--container CONTAINER> [-h] [-t] [-n num] [-q] # Display recent log output for run containers
 run:stop <app|--container CONTAINER>                         # Stops all run containers for an app or a specified run container
@@ -29,6 +29,16 @@ dokku run --env "NODE_ENV=development" --env "PATH=/custom/path" node-js-app npm
 
 One off containers are removed at the end of process execution.
 
+In addition, one-off containers also run for a max of 24 hours (86400 seconds) by default, after which they are reaped. This can be changed by setting the `--ttl-seconds` argument:
+
+
+```shell
+# runs for 10 minutes
+dokku run --ttl-seconds 600 node-js-app npm run mytask
+```
+
+One-off containers that exceed their runtime are reaped every 5 minutes, so the ttl-seconds is an approximation and your app may end up running for up to 5 minutes longer than expected.
+
 #### Running Procfile commands
 
 The `run` command can also be used to run a command defined in the app `Procfile`:

docs/processes/scheduled-cron-tasks.md

@@ -43,6 +43,8 @@ A cron task takes the following properties:
 
 Zero or more cron tasks can be specified per app. Cron tasks 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.
 
+Cron tasks can run for a maximum of 24 hours via the docker-local scheduler, after which they are reaped from the system.
+
 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.
 
 #### Task Environment