From 350a84d253fcaf8262f526fe9353a20692c0e229 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Tue, 27 Jul 2021 02:11:43 -0400 Subject: [PATCH] refactor: deprecate the --detach flag in favor of run:detached --- docs/appendices/0.25.0-migration-guide.md | 2 +- docs/configuration/environment-variables.md | 8 ++++---- docs/processes/one-off-tasks.md | 14 ++++++++++---- plugins/common/functions | 1 + plugins/run/help-functions | 1 + plugins/run/internal-functions | 10 ++++++++++ plugins/run/subcommands/detached | 6 ++++++ tests/unit/run_2.bats | 4 ++-- 8 files changed, 35 insertions(+), 11 deletions(-) create mode 100755 plugins/run/subcommands/detached diff --git a/docs/appendices/0.25.0-migration-guide.md b/docs/appendices/0.25.0-migration-guide.md index f94cea26c..ac70f9252 100644 --- a/docs/appendices/0.25.0-migration-guide.md +++ b/docs/appendices/0.25.0-migration-guide.md @@ -5,8 +5,8 @@ - The network plugin can now set an `initial-network` for all containers on creation. This is a replacement for specifying the `--network` flag via the `docker-options` plugin. Please see the [network documentation](/docs/networking/network.md#attaching-an-app-to-a-network) for more information. - The `dokku run` command now always removes the ephemeral container on exit. Users that need a persistent container should instead specify a `console` process type in their `Procfile` specifying an available shell (usually either `bash` or `sh`) and scale that container appropriately. - ## Deprecations - In previous versions of Dokku, the only way to specify a custom `Dockerfile` was to use the `docker-options` plugin to set the `--file` flag for a docker build. As of 0.25.0, the `builder-dockerfile:set` command should be used instead, as outlined in the [docs here](/docs/deployment/builders/dockerfiles.md#changingthe-dockerfile-location). Usage of the old method should be migrated to the new method. - The `--rm` and ``--rm-container` flags may be specified but no longer have any effect on `dokku run`. +- The `--detach` flag is deprecated in favor of the `run:detached` command. diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index 09a4473e2..2914a6d03 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -91,11 +91,11 @@ The following config variables have special meanings and can be set in a variety | `DOKKU_EVENTS_LOGFILE` | `$DOKKU_LOGS_DIR/events.log` | `/etc/environment`
`~dokku/.dokkurc`
`~dokku/.dokkurc/*` | Where the events log file is written to. | | `DOKKU_APP_NAME` | none | `--app APP` flag | Name of application to work on. Respected by core plugins. | | `DOKKU_APPS_FORCE_DELETE` | none | `--force` flag | Whether to force delete an application. Also used by other plugins for destructive actions. | -| `DOKKU_CHECKS_URL` | `https://dokku.com/docs/deployment/zero-downtime-deploys/` | `/etc/environment`
`~dokku/.dokkurc`
`~dokku/.dokkurc/*` | Url displayed during deployment when no CHECKS file exists. | -| `DOKKU_DETACH_CONTAINER` | none | `--detach` flag | Whether to detach a container started via `dokku run`. | +| `DOKKU_CHECKS_URL` | `https://dokku.com/docs/deployment/zero-downtime-deploys/` | `/etc/environment`
`~dokku/.dokkurc`
`~dokku/.dokkurc/*` | Url displayed during deployment when no CHECKS file exists. | +| `DOKKU_DETACH_CONTAINER` | none | `--detach` flag | Deprecated: Whether to detach a container started via `dokku run`. | | `DOKKU_QUIET_OUTPUT` | none | `--quiet` flag | Silences certain header output for `dokku` commands. | -| `DOKKU_RM_CONTAINER` | none | `dokku config:set`
| Deprecated: Whether to keep `dokku run` containers around or not. | -| `DOKKU_TRACE` | none | `dokku trace:on`
`dokku trace:off`
`--trace` flag | Turn on very verbose debugging. | +| `DOKKU_RM_CONTAINER` | none | `dokku config:set`
| Deprecated: Whether to keep `dokku run` containers around or not. | +| `DOKKU_TRACE` | none | `dokku trace:on`
`dokku trace:off`
`--trace` flag | Turn on very verbose debugging. | | `DOKKU_APP_PROXY_TYPE` | `nginx` | `dokku proxy:set` | | | `DOKKU_APP_RESTORE` | `1` | `dokku config:set`
`dokku ps:stop` | | | `DOKKU_APP_SHELL` | `/bin/bash` | `dokku config:set` | Allows users to change the default shell used by Dokku for `dokku enter` and execution of deployment tasks. | diff --git a/docs/processes/one-off-tasks.md b/docs/processes/one-off-tasks.md index c4e5483d5..bc586fbdd 100644 --- a/docs/processes/one-off-tasks.md +++ b/docs/processes/one-off-tasks.md @@ -8,6 +8,8 @@ Sometimes it is necessary to run a one-off command under an application. Dokku m ## Usage +### Running a one-off command + 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. This contianer will be removed after the process exits. The container image will be the same container image as was used to start the currently deployed application. ```shell @@ -18,6 +20,8 @@ dokku run node-js-app ls -lah dokku run --env "NODE_ENV=development" --env "PATH=/custom/path" node-js-app npm run mytask ``` +#### Running Procfile commands + The `run` command can also be used to run a command defined in the app `Procfile`: ``` @@ -29,17 +33,19 @@ console: bundle exec racksh dokku run my-app console ``` +#### Specifying container labels + 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. +### Running a detached container + +Finally, a container can be run in "detached" mode via the `run:detached` Dokku command. 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 +dokku run:detached 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. diff --git a/plugins/common/functions b/plugins/common/functions index bfe8c2757..938c56d4c 100755 --- a/plugins/common/functions +++ b/plugins/common/functions @@ -433,6 +433,7 @@ parse_args() { export DOKKU_QUIET_OUTPUT=1 ;; --detach) + dokku_log_warn_quiet "Deprecated: use run:detached instead of using the --detach flag" export DOKKU_DETACH_CONTAINER=1 ;; --trace) diff --git a/plugins/run/help-functions b/plugins/run/help-functions index 12db5bc05..0c1671720 100755 --- a/plugins/run/help-functions +++ b/plugins/run/help-functions @@ -28,5 +28,6 @@ fn-help-content() { declare desc="return help content" cat < , Run a command in a new container using the current application image + run:detached [--env KEY=VALUE] , Run a command in a new detached container using the current application image help_content } diff --git a/plugins/run/internal-functions b/plugins/run/internal-functions index 977a23903..8ebc6cc90 100755 --- a/plugins/run/internal-functions +++ b/plugins/run/internal-functions @@ -60,3 +60,13 @@ cmd-run() { export DOKKU_RM_CONTAINER=1 fn-run "$@" } + +cmd-run-detached() { + declare desc="run a detached container" + declare cmd="run:detached" + [[ "$1" == "$cmd" ]] && shift 1 + + export DOKKU_DETACH_CONTAINER=1 + export DOKKU_RM_CONTAINER=1 + fn-run "$@" +} diff --git a/plugins/run/subcommands/detached b/plugins/run/subcommands/detached new file mode 100755 index 000000000..637af4a18 --- /dev/null +++ b/plugins/run/subcommands/detached @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +set -eo pipefail +source "$PLUGIN_AVAILABLE_PATH/run/internal-functions" +[[ $DOKKU_TRACE ]] && set -x + +cmd-run-detached "$@" diff --git a/tests/unit/run_2.bats b/tests/unit/run_2.bats index 25994fcd5..0be97ab67 100644 --- a/tests/unit/run_2.bats +++ b/tests/unit/run_2.bats @@ -26,10 +26,10 @@ teardown() { assert_failure } -@test "(core) run (detached)" { +@test "(core) run:detached" { deploy_app - RANDOM_RUN_CID="$(dokku --label=com.dokku.test-label=value --detach run $TEST_APP sleep 300)" + RANDOM_RUN_CID="$(dokku --label=com.dokku.test-label=value run:detached $TEST_APP sleep 300)" run /bin/bash -c "docker inspect -f '{{ .State.Status }}' $RANDOM_RUN_CID" echo "output: $output" echo "status: $status"