Mirrors/dokku
1
0
Fork 0
mirror of https://github.com/dokku/dokku.git synced 2025-12-16 20:17:44 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
f8ccf5207930cda3368471f589d94795f6e38929
dokku/docs/configuration/environment-variables.md

125 lines
17 KiB
Markdown
Raw Normal View History

Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
# Environment Variables
Consolidate readme/wiki docs into organized docs folder
2014-10-04 04:24:22 -04:00
various grammar fixes, spell fixes and added missing words
2014-10-05 22:36:01 +02:00
Typically an application will require some configuration to run properly. Dokku supports application configuration via environment variables. Environment variables may contain private data, such as passwords or API keys, so it is not recommended to store them in your application's repository.
Consolidate readme/wiki docs into organized docs folder
2014-10-04 04:24:22 -04:00
The `config` plugin provides the following commands to manage your variables:
```
Update config command to config:show Dokku now gives `config` deprecation message, and suggests to use `config:show`
2021-03-27 23:36:52 -06:00
config:show (<app>|--global) Pretty-print an app or global environment
feat: add config:clear command Closes #3537
2019-05-20 13:25:04 -07:00
config:bundle (<app>|--global) [--merged] Bundle environment into tarfile
config:clear (<app>|--global) Clears environment variables
config:export (<app>|--global) [--envfile] Export a global or app environment
Update output of `config:help` in docs [ci skip]
2018-05-25 19:51:35 +09:00
config:get (<app>|--global) KEY Display a global or app-specific config value
feat: add config:clear command Closes #3537
2019-05-20 13:25:04 -07:00
config:keys (<app>|--global) [--merged] Show keys set in environment
Update output of `config:help` in docs [ci skip]
2018-05-25 19:51:35 +09:00
config:set [--encoded] [--no-restart] (<app>|--global) KEY1=VALUE1 [KEY2=VALUE2 ...] Set one or more config vars
config:unset [--no-restart] (<app>|--global) KEY1 [KEY2 ...] Unset one or more config vars
Consolidate readme/wiki docs into organized docs folder
2014-10-04 04:24:22 -04:00
```
docs: clarify usage of build args to set environment variables for Dockerfile deploys While documented under Dockerfile deploys, developers looking at docs might not know to go to those docs to find this information out.
2022-06-27 10:53:09 -04:00
> For security reasons - and as per [docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available _only_ during runtime, as noted in [this issue](https://github.com/dokku/dokku/issues/1860). Consider using [build arguments](/docs/deployment/builders/dockerfiles.md#build-time-configuration-variables) to expose variables during build-time for Dockerfile apps.
Consolidate readme/wiki docs into organized docs folder
2014-10-04 04:24:22 -04:00
docs: better callout for why env vars do not get applied to dockerfile builds [ci skip]
2018-06-25 12:15:24 -04:00
Environment variables are available both at run time and during the application build/compilation step for buildpack-based deploys.
Add documentation for the recent build-env feature addition
2014-12-12 09:54:26 -05:00
docs: more cleanup
2021-07-09 23:06:38 -04:00
For buildpack deploys, Dokku will create a `/app/.env` file that can be used for legacy buildpacks. Note that this is _not_ updated when `config:set` or `config:unset` is called, and is only written during a `deploy` or `ps:rebuild`. Developers are encouraged to instead read from the application environment directly, as the proper values will be available then.
Add documentation surrounding when the /app/.env file is populated Closes #2177 [ci skip]
2016-06-26 17:13:46 -04:00
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
> Note: Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications.
You can set multiple environment variables at once:
```shell
dokku config:set node-js-app ENV=prod COMPILE_ASSETS=1
```
[config] update docs
2017-07-16 19:51:27 -04:00
> Note: Whitespace and special characters get tricky. If you are using dokku locally you don't need to do any special escaping. If you are using dokku over ssh you will need to backslash-escape spaces:
```shell
dokku config:set node-js-app KEY="VAL\ WITH\ SPACES"
```
Dokku can also read base64 encoded values. That's the easiest way to set a value with newlines or spaces. To set a value with newlines you need to base64 encode it first and pass the `--encoded` flag:
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
```shell
[config] update docs
2017-07-16 19:51:27 -04:00
dokku config:set --encoded node-js-app KEY="$(base64 ~/.ssh/id_rsa)"
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
```
Various small doc updates Replaces #1622, addresses comments by @josegonzalez [ci skip]
2015-11-04 21:26:54 -06:00
When setting or unsetting environment variables, you may wish to avoid an application restart. This is useful when developing plugins or when setting multiple environment variables in a scripted manner. To do so, use the `--no-restart` flag:
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
```shell
--no-restart option after config:set not before
2016-01-04 22:52:04 +01:00
dokku config:set --no-restart node-js-app ENV=prod
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
```
[config] update docs
2017-07-16 19:51:27 -04:00
If you wish to have the variables output in an `eval`-compatible form, you can use the `config:export` command
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
```shell
[config] update docs
2017-07-16 19:51:27 -04:00
dokku config:export node-js-app
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
# outputs variables in the form:
#
# export ENV='prod'
# export COMPILE_ASSETS='1'
# source in all the node-js-app app environment variables
[config] restore `dokku config` functionality and fix docs
2017-10-01 22:50:01 -04:00
eval $(dokku config:export node-js-app)
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
```
[config] restore `dokku config` functionality and fix docs
2017-10-01 22:50:01 -04:00
You can control the format of the exported variables with the `--format` flag.
`--format=shell` will output the variables in a single-line for usage in command-line utilities:
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
```shell
[config] restore `dokku config` functionality and fix docs
2017-10-01 22:50:01 -04:00
dokku config:export --format shell node-js-app
Flesh out documentation on application configuration Added documentation on little-known flags and also renamed the section "Environment Variables"
2015-10-14 05:23:57 -04:00
# outputs variables in the form:
#
# ENV='prod' COMPILE_ASSETS='1'
```
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
## Special Config Variables
docs: clarify that special config variables are not exposed to applications Closes #4093 [ci skip]
2020-08-01 20:43:36 -04:00
The following config variables have special meanings and can be set in a variety of ways. Unless specified via global app config, the values may not be passed into applications. Usage of these values within applications should be considered unsafe, as they are an internal configuration values that may be moved to the internal properties system in the future.
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
> Warning: This list is not exhaustive, and may vary from version to version.
| Name | Default | How to modify | Description |
| ------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `DOKKU_ROOT` | `~dokku` | `/etc/environment` | The root directory where dokku will store application repositories, as well as certain configuration files. |
refactor: rename command to :set-property This will allow us to set other property values for the buildpacks plugin.
2021-01-23 18:17:40 -05:00
| `DOKKU_IMAGE` | `gliderlabs/herokuish` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The default image to use when building herokuish containers. Deprecated in favor of using `buildpacks:set-property` |
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
| `DOKKU_LIB_ROOT` | `/var/lib/dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory where plugins, certain data, and general configuration is stored. |
| `PLUGIN_PATH` | `$DOKKU_LIB_ROOT/plugins"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The top-level directory where plugins are stored. |
| `PLUGIN_AVAILABLE_PATH` | `$PLUGIN_PATH/available"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that holds all available plugins, including core. |
| `PLUGIN_ENABLED_PATH` | `$PLUGIN_PATH/enabled"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that holds all enabled plugins, including core. |
| `PLUGIN_CORE_PATH` | `$DOKKU_LIB_ROOT/core-plugins"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that stores all core plugins. |
| `PLUGIN_CORE_AVAILABLE_PATH` | `$PLUGIN_CORE_PATH/available"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that stores all available core plugins. |
| `PLUGIN_CORE_ENABLED_PATH` | `$PLUGIN_CORE_PATH/enabled"` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | The directory that stores all enabled core plugins. |
| `DOKKU_LOGS_DIR` | `/var/log/dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | Where dokku logs should be written to. |
feat: actually mount the apps log dir Also fix it so that the log directory is mountable from a custom path on the host if running dokku within a container.
2021-01-04 21:45:26 -05:00
| `DOKKU_LOGS_HOST_DIR` | `$DOKKU_LOGS_DIR` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | A path on the host that will be mounted into the vector logging container. |
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
| `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. |
refactor: deprecate the --detach flag in favor of run:detached
2021-07-27 02:11:43 -04:00
| `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. |
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
| `DOKKU_QUIET_OUTPUT` | none | `--quiet` flag | Silences certain header output for `dokku` commands. |
refactor: deprecate the --detach flag in favor of run:detached
2021-07-27 02:11:43 -04:00
| `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. |
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
| `DOKKU_APP_PROXY_TYPE` | `nginx` | `dokku proxy:set` | |
| `DOKKU_APP_RESTORE` | `1` | `dokku config:set` <br /> `dokku ps:stop` | |
feat: add support for configuring the app shell This allows developers to change the shell from /bin/bash to any other when executing `dokku enter` or pre/post deployment tasks. Ideally we could detect the shells available, but that is slow and potentially error prone. Closes #2572
2018-03-03 22:11:00 -05:00
| `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. |
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
| `DOKKU_APP_TYPE` | `herokuish` | Auto-detected by using buildpacks or dockerfile | |
| `DOKKU_CHECKS_DISABLED` | none | `dokku checks:disable` | |
| `DOKKU_CHECKS_ENABLED` | none | `dokku checks:enable` | |
| `DOKKU_CHECKS_SKIPPED` | none | `dokku checks:skip` | |
| `DOKKU_CHECKS_WAIT` | `5` | `dokku config:set` | Wait this many seconds for the container to start before running checks.
| `DOKKU_CHECKS_TIMEOUT` | `30` | `dokku config:set` | Wait this many seconds for each response before marking it as a failure.
| `DOKKU_CHECKS_ATTEMPTS` | `5` | `dokku config:set` | Number of retries for to run for a specific check before marking it as a failure
| `DOKKU_DEFAULT_CHECKS_WAIT` | `10` | `dokku config:set` | If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running. |
| `DOKKU_DISABLE_PROXY` | none | `dokku proxy:disable` <br /> `dokku proxy:enable` | Disables the proxy in front of your application, resulting in publicly routing the docker container. |
feat: Add the ability to disable ANSI prefixes via DOKKU_DISABLE_ANSI_PREFIX_REMOVAL To disable the removal, set the value of this variable to `true`. Closes #2644
2018-02-19 15:07:04 -05:00
| `DOKKU_DISABLE_ANSI_PREFIX_REMOVAL` | none | `dokku config:set` <br /> `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | Disables removal of the ANSI prefix during deploys. Can be used in cases where the client deployer does not understand ansi escape codes. |
Add configuration option to disable automatic app creation Fixes #2808
2017-10-20 23:25:58 -04:00
| `DOKKU_DISABLE_APP_AUTOCREATION` | none | `dokku config:set` | Disables automatic creation of a non-existent app on deploy. |
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
| `DOKKU_DOCKER_STOP_TIMEOUT` | `10` | `dokku config:set` | Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands _also_ respect this value. If not specified, the docker defaults for the [docker stop command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.|
| `DOKKU_DOCKERFILE_CACHE_BUILD` | none | `dokku config:set` | |
| `DOKKU_DOCKERFILE_START_CMD` | none | `dokku config:set` | |
feat: allow users to specify custom parallel arguments
2019-06-10 13:07:23 -04:00
| `DOKKU_PARALLEL_ARGUMENTS`. | none | `dokku config:set` | Allows passing custom arguments to parallel for `ps:*all` commands |
feat: add global fallback for DOKKU_PROXY_PORT and DOKKU_PROXY_SSL_PORT
2019-11-26 12:30:51 +01:00
| `DOKKU_PROXY_PORT` | automatically assigned | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` <br /> `dokku config:set` | |
| `DOKKU_PROXY_SSL_PORT` | automatically assigned | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` <br /> `dokku config:set` | |
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
| `DOKKU_SKIP_ALL_CHECKS` | none | `dokku config:set` | |
refactor: allow skipping cleanup on a per-application basis Also move all cleanup-related logic into docker_cleanup method
2017-07-02 16:54:26 -06:00
| `DOKKU_SKIP_CLEANUP` | | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | When a deploy is triggered, if this is set to a non-empty value, then old docker containers and images will not be removed. |
feat: document special dokku environment variables This adds a table of environment variables that Dokku will use to change internal behavior. Not all are fully documented/listed, but this should be enough to get people hacking. [ci skip]
2017-05-23 01:45:30 -06:00
| `DOKKU_SKIP_DEFAULT_CHECKS` | | `dokku config:set` | |
| `DOKKU_SKIP_DEPLOY` | | `dokku config:set` | |
feat: allow users to customize the container start command This can be useful when testing base images that are similar to herokuish but have a different entrypoint.
2019-08-20 17:12:18 -04:00
| `DOKKU_START_CMD` | none | `dokku config:set` | Command to run instead of `/start $PROC_TYPE` |
feat: allow changing the system user the properties plugin uses
2018-01-12 04:23:07 -05:00
| `DOKKU_SYSTEM_GROUP` | `dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | System group to chown files as. |
| `DOKKU_SYSTEM_USER` | `dokku` | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | System user to chown files as. |
Reference in New Issue Copy Permalink