Improve This Doc

Environment Variables

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.

The config plugin provides the following commands to manage your variables:

config (<app>|--global)                                   Display all global or app-specific config vars
config:get (<app>|--global) KEY                           Display a global or app-specific config value
config:set (<app>|--global) KEY1=VALUE1 [KEY2=VALUE2 ...] Set one or more config vars
config:unset (<app>|--global) KEY1 [KEY2 ...]             Unset one or more config vars

The variables are available both at run time and during the application build/compilation step for buildpack-based deploys. For security reasons - and as per docker recommendations - Dockerfile-based deploys have variables available only during runtime, as noted in this issue.

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.

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:

dokku config:set node-js-app ENV=prod COMPILE_ASSETS=1

When setting variables with whitespaces, you need to escape them:

dokku config:set node-js-app KEY=\"VAL\ WITH\ SPACES\"

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:

dokku config:set --no-restart node-js-app ENV=prod

If you wish to have the variables output in an eval-compatible form, you can use the --export flag:

dokku config node-js-app --export
# outputs variables in the form:
#
#   export ENV='prod'
#   export COMPILE_ASSETS='1'

# source in all the node-js-app app environment variables
eval $(dokku config node-js-app --export)

You can also output the variables in a single-line for usage in command-line utilities with the --shell flag:

dokku config node-js-app --shell

# outputs variables in the form:
#
#   ENV='prod' COMPILE_ASSETS='1'

Special Config Variables

The following list config variables have special meaning and can be set in a variety of ways.

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.
DOKKU_IMAGE gliderlabs/herokuish /etc/environment
~dokku/.dokkurc
~dokku/.dokkurc/*
The default image to use when building herokuish containers.
DOKKU_LIB_ROOT /var/lib/dokku /etc/environment
~dokku/.dokkurc
~dokku/.dokkurc/*
The directory where plugins, certain data, and general configuration is stored.
PLUGIN_PATH $DOKKU_LIB_ROOT/plugins" /etc/environment
~dokku/.dokkurc
~dokku/.dokkurc/*
The top-level directory where plugins are stored.
PLUGIN_AVAILABLE_PATH $PLUGIN_PATH/available" /etc/environment
~dokku/.dokkurc
~dokku/.dokkurc/*
The directory that holds all available plugins, including core.
PLUGIN_ENABLED_PATH $PLUGIN_PATH/enabled" /etc/environment
~dokku/.dokkurc
~dokku/.dokkurc/*
The directory that holds all enabled plugins, including core.
PLUGIN_CORE_PATH $DOKKU_LIB_ROOT/core-plugins" /etc/environment
~dokku/.dokkurc
~dokku/.dokkurc/*
The directory that stores all core plugins.
PLUGIN_CORE_AVAILABLE_PATH $PLUGIN_CORE_PATH/available" /etc/environment
~dokku/.dokkurc
~dokku/.dokkurc/*
The directory that stores all available core plugins.
PLUGIN_CORE_ENABLED_PATH $PLUGIN_CORE_PATH/enabled" /etc/environment
~dokku/.dokkurc
~dokku/.dokkurc/*
The directory that stores all enabled core plugins.
DOKKU_LOGS_DIR /var/log/dokku /etc/environment
~dokku/.dokkurc
~dokku/.dokkurc/*
Where dokku logs should be written to.
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_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_APP_PROXY_TYPE nginx dokku proxy:set
DOKKU_APP_RESTORE 1 dokku config:set
dokku ps:stop
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_DEPLOY_BRANCH master dokku config:set Branch to deploy by default.
DOKKU_DISABLE_PROXY none dokku proxy:disable
dokku proxy:enable
Disables the proxy in front of your application, resulting in publicly routing the docker container.
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 will be used.
DOKKU_DOCKERFILE_CMD dockerfile cmd dokku config:set
DOKKU_DOCKERFILE_CACHE_BUILD none dokku config:set
DOKKU_DOCKERFILE_ENTRYPOINT dockerfile entrypoint dokku config:set
DOKKU_DOCKERFILE_PORTS dockerfile ports dokku config:set
DOKKU_DOCKERFILE_START_CMD none dokku config:set
DOKKU_NGINX_PORT automatically assigned dokku config:set
DOKKU_NGINX_SSL_PORT automatically assigned dokku config:set
DOKKU_PROXY_PORT_MAP automatically assigned dokku proxy:ports-add
dokku proxy:ports-remove, dokku proxy:ports-clear
DOKKU_SKIP_ALL_CHECKS none dokku config:set
DOKKU_SKIP_CLEANUP /etc/environment
~dokku/.dokkurc
~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.
DOKKU_SKIP_DEFAULT_CHECKS dokku config:set
DOKKU_SKIP_DEPLOY dokku config:set
DOKKU_WAIT_TO_RETIRE 60 dokku config:set After a successful deploy, the grace period given to old containers before they are stopped/terminated. This is useful for ensuring completion of long-running http connections.
  v: master
Versions
On GitHub
View
Edit

Free document hosting provided by Viewdocs.