diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md index a167f728c..a1b729960 100644 --- a/ISSUE_TEMPLATE.md +++ b/ISSUE_TEMPLATE.md @@ -29,9 +29,7 @@ ### Additional information -- Container Inspect Output (if applicable): - - 0.13.0+: `dokku inspect APP_NAME` - - <0.13.0: `docker inspect CONTAINER_ID`: WARNING, `docker inspect` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX. +- Container Inspect Output (if applicable) via `dokku inspect APP_NAME` - `cat /home/dokku//nginx.conf` (if applicable): - Link to the exact repository being deployed (if possible/applicable): - If a deploy is failing or behaving unexpectedly: @@ -40,5 +38,5 @@ - If using buildpacks, which custom buildpacks are in use - If using a `Dockerfile`, the contents of that file - If it exists, the contents of your `Procfile`. -- Output of failing Dokku commands after running `dokku trace on` - (BEWARE: `trace on` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX): +- Output of failing Dokku commands after running `dokku trace:on` + (BEWARE: `trace:on` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX): diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index 435372e09..c6a5cfda6 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -92,7 +92,7 @@ The following list config variables have special meaning and can be set in a var | `DOKKU_DETACH_CONTAINER` | none | `--detach` flag | 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`
`--rm-container` flag
`--rm` flag | Whether to keep `dokku run` containers around or not. | -| `DOKKU_TRACE` | none | `dokku trace on`
`dokku trace false`
`--trace` flag | Turn on very verbose debugging. | +| `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/getting-started/troubleshooting.md b/docs/getting-started/troubleshooting.md index 627664275..ed8181aad 100644 --- a/docs/getting-started/troubleshooting.md +++ b/docs/getting-started/troubleshooting.md @@ -1,5 +1,38 @@ # Troubleshooting +> New as of 0.17.0 + +``` +trace:on # Enables trace mode +trace:off # Disables trace mode +``` + +## Trace Mode + +By default, Dokku will constrain the amount of output displayed for any given command run. The verbosity of output can be increased by enabling trace mode. Trace mode will turn on the `set -x` flag for bash plugins, while other plugins are free to respect the environment variable `DOKKU_TRACE` and log differently as approprate. Trace mode can be useful to see _where_ plugins are running commands that would otherwise be unexpected. + +To enable trace mode, run `trace:on` + +```shell +dokku trace:on +``` + +``` +-----> Enabling trace mode +``` + +Trace mode can be disabled with `trace:off` + +```shell +dokku trace:off +``` + +``` +-----> Disabling trace mode +``` + +## Common Problems + __Symptom:__ I deployed my app but I am getting the default nginx page. __Solution:__ @@ -41,22 +74,7 @@ __Symptom:__ I want to deploy my app, but while pushing I get the following erro __Solution:__ -The `remote rejected` error does not give enough information. Anything could have failed. - -To enable Dokku tracing, simply run the following command: - -```shell -# since 0.3.9 -dokku trace on -``` - -In versions older than 0.3.9, you can create a `/home/dokku/dokkurc` file containing the following: - -```shell -export DOKKU_TRACE=1 -``` - -This will trace all of Dokku's activity. If this does not help you, create a [gist](https://gist.github.com) containing the full log, and create an issue. +The `remote rejected` error does not give enough information. Anything could have failed. Enable trace mode and begin debugging. If this does not help you, create a [gist](https://gist.github.com) containing the full log, and create an issue. *** diff --git a/plugins/trace/commands b/plugins/trace/commands new file mode 100755 index 000000000..4e8ffb885 --- /dev/null +++ b/plugins/trace/commands @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +[[ " help trace:help " == *" $1 "* ]] || exit "$DOKKU_NOT_IMPLEMENTED_EXIT" +source "$PLUGIN_AVAILABLE_PATH/trace/internal-functions" +set -eo pipefail +[[ $DOKKU_TRACE ]] && set -x + +case "$1" in + help | trace:help) + trace_help_cmd "$@" + ;; + + *) + exit "$DOKKU_NOT_IMPLEMENTED_EXIT" + ;; + +esac diff --git a/plugins/trace/internal-functions b/plugins/trace/internal-functions new file mode 100755 index 000000000..c055b7a50 --- /dev/null +++ b/plugins/trace/internal-functions @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions" + +trace_help_content_func() { + declare desc="return trace plugin help content" + cat <"$DOKKU_ROOT/.dokkurc/DOKKU_TRACE" fi if [[ "$2" == "off" ]]; then - echo "Disabling dokku trace" + dokku_log_info1 "Disabling trace mode" rm -f "$DOKKU_ROOT/.dokkurc/DOKKU_TRACE" fi } -dokku_trace_cmd "$@" +trace_default_cmd "$@" diff --git a/plugins/trace/subcommands/off b/plugins/trace/subcommands/off new file mode 100755 index 000000000..a7f44c0eb --- /dev/null +++ b/plugins/trace/subcommands/off @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +set -eo pipefail +[[ $DOKKU_TRACE ]] && set -x +source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions" + +trace_off_cmd() { + declare desc="disables trace mode" + local cmd="trace" + [[ -d $DOKKU_ROOT/.dokkurc ]] || mkdir -p "$DOKKU_ROOT/.dokkurc" + + dokku_log_info1 "Disabling trace mode" + rm -f "$DOKKU_ROOT/.dokkurc/DOKKU_TRACE" +} + +trace_off_cmd "$@" diff --git a/plugins/trace/subcommands/on b/plugins/trace/subcommands/on new file mode 100755 index 000000000..694791b16 --- /dev/null +++ b/plugins/trace/subcommands/on @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +set -eo pipefail +[[ $DOKKU_TRACE ]] && set -x +source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions" + +trace_on_cmd() { + declare desc="enables trace mode" + local cmd="trace" + [[ -d $DOKKU_ROOT/.dokkurc ]] || mkdir -p "$DOKKU_ROOT/.dokkurc" + + dokku_log_info1 "Enabling trace mode" + echo "export DOKKU_TRACE=1" >"$DOKKU_ROOT/.dokkurc/DOKKU_TRACE" +} + +trace_on_cmd "$@"