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

refactor: deprecate the --detach flag in favor of run:detached

Browse Source
This commit is contained in:
Jose Diaz-Gonzalez
2021-07-27 02:11:43 -04:00
parent 618158a0f3
commit 350a84d253
8 changed files with 35 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/appendices/0.25.0-migration-guide.md
View File

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

8
docs/configuration/environment-variables.md
View File

@@ -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` <br /> `~dokku/.dokkurc` <br /> `~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` <br /> `~dokku/.dokkurc` <br /> `~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` <br /> `~dokku/.dokkurc` <br /> `~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` <br /> | Deprecated: Whether to keep `dokku run` containers around or not. |
| `DOKKU_TRACE` | none | `dokku trace:on` <br /> `dokku trace:off` <br /> `--trace` flag | Turn on very verbose debugging. |
| `DOKKU_RM_CONTAINER` | none | `dokku config:set` <br /> | Deprecated: Whether to keep `dokku run` containers around or not. |
| `DOKKU_TRACE` | none | `dokku trace:on` <br /> `dokku trace:off` <br /> `--trace` flag | Turn on very verbose debugging. |
| `DOKKU_APP_PROXY_TYPE` | `nginx` | `dokku proxy:set` | |
| `DOKKU_APP_RESTORE` | `1` | `dokku config:set` <br /> `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. |

14
docs/processes/one-off-tasks.md
View File

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

1
plugins/common/functions
View File

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

1
plugins/run/help-functions
View File

@@ -28,5 +28,6 @@ fn-help-content() {
declare desc="return help content"
cat <<help_content
run [--env KEY=VALUE] <app> <cmd>, Run a command in a new container using the current application image
run:detached [--env KEY=VALUE] <app> <cmd>, Run a command in a new detached container using the current application image
help_content
}

10
plugins/run/internal-functions
View File

@@ -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 "$@"
}

6
plugins/run/subcommands/detached Executable file
View File

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

4
tests/unit/run_2.bats
View File

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