How to manage your application’s environment variables#
Your application relies on environment variables to configure its settings as well as to access storage, databases and other services.
Environment variables can be set independently for each environment, either in the cloud or locally. They can also be briefly categorized into two categories:
Built-in environment variables which are automatically set by our infrastructure.
Custom environment variables which are user configurable and can also be used to overwrite environment variables of the previous category.
See also
Using the Divio CLI#
Retrieve custom environment variables from the default cloud environment (test):
divio app environment-variables list
Output:
Environment: test (<environment uuid>)
+--------------------+------------------+----------------+
| name | value | is_sensitive |
+====================+==================+================+
| SIMPLE_VAR_NAME | SIMPLE VAR VALUE | False |
+--------------------+------------------+----------------+
| SENSITIVE_VAR_NAME | | True |
+--------------------+------------------+----------------+
Note
The values of the sensitive environment variables are represented as empty cells in table format. This should not be confused with environment variables of blank values. You should always check the is_sensitive column to distinguish between the two.
All environment variables commands produce results that can be displayed in table (default), JSON or txt-like format. The latter will only, for simplicity purposes, include names and values and not include sensitive environment variables at all. It is worth noting that the JSON format will include additional information in most cases. For example, the above command could also be expressed in the following way:
divio app environment-variables --json list
Output:
[
{
"environment": "test",
"environment_uuid": "<environment uuid>",
"environment_variables": [
{
"uuid": "<environment variable uuid>",
"name": "SIMPLE_VAR_NAME",
"value": "SIMPLE VAR VALUE",
"order": 1,
"is_sensitive": false,
"is_read_only": false
},
{
"uuid": "<environment variable uuid>",
"name": "SENSITIVE_VAR_NAME",
"order": 2,
"is_sensitive": true,
"is_read_only": false
}
]
}
]
Or:
divio app environment-variables --txt list
Output:
Environment: test (<environment uuid>)
--------------------------------------
SIMPLE_VAR_NAME=SIMPLE VAR VALUE
Note
As you may have already noticed, the value field of sensitive environment variables is completely absent in JSON format. In TXT format, sensitive environment variables are not included at all.
Retrieve custom environment variables from another environment such as the
live one, using the -e option:
divio app environment-variables list -e live
Retrieve custom environment variables across all environments of an
application using the --all-envs flag:
divio app environment-variables list --all-envs
Retrieve a specific custom environment variable from the default cloud environment (test):
divio app environment-variables get SIMPLE_VAR_NAME
Output:
Environment: test (<environment uuid>)
+--------------------+------------------+----------------+
| name | value | is_sensitive |
+====================+==================+================+
| SIMPLE_VAR_NAME | SIMPLE VAR VALUE | False |
+--------------------+------------------+----------------+
Retrieve any occurrence of a specific custom environment variable across all
environments of an application using the --all-envs flag:
divio app environment-variables get SIMPLE_VAR_NAME --all-envs
Important
An important distinction between custom and built-in environment variables can also be noticeable while trying to retrieve the latter. To retrieve a built-in environment variable you must first specify the deployment in which it was registered by following the steps below:
First, list the deployments of the corresponding environment and extract the uuid of the one you are interested in. This example is based on the use case of the live environment.
divio app deployments list -e live
Output:
Environment: live (<environment uuid>)
+-------------------+---------------+-----------------------------+-----------------------------+----------------------+
| uuid | author | started_at | ended_at | status | success |
+===================+===============+=============================+=============================+==========+===========+
| <deployment_uuid> | <author_uuid> | 2023-02-14T10:35:43.609956Z | 2023-02-14T10:36:54.635565Z | done | True |
+-------------------+---------------+-----------------------------+-----------------------------+----------+-----------+
| <deployment_uuid> | <author_uuid> | 2023-02-13T20:17:13.869451Z | 2023-02-13T20:18:18.915017Z | done | True |
+-------------------+---------------+-----------------------------+-----------------------------+----------+-----------+
Retrieve the deployment of your interest which will also include the names of all available environment variables previously registered for this specific deployment (optional step).
divio app deployments get <deployment_uuid>
Output:
Environment: test (<environment uuid>)
+-----------------------+------------------------------------------------+
| uuid | <deployment_uuid> |
+-----------------------+------------------------------------------------+
| author | <author_uuid> |
+-----------------------+------------------------------------------------+
| started_at | 2023-02-15T23:11:31.336332Z |
+-----------------------+------------------------------------------------+
| ended_at | 2023-02-15T23:12:45.554147Z |
+-----------------------+------------------------------------------------+
| status | done |
+-----------------------+------------------------------------------------+
| success | True |
+-----------------------+------------------------------------------------+
| environment_variables | DEBUG, STAGE, DOMAIN, SSO_DSN, CACHE_URL, |
| | SITE_NAME, GIT_BRANCH, GIT_COMMIT, SECRET_KEY, |
| | DATABASE_URL, DOMAIN_ALIASES, TEMPLATE_DEBUG, |
| | SIMPLE_VAR_NAME, DOMAIN_REDIRECTS, |
| | DEFAULT_STORAGE_DSN, DEFAULT_DATABASE_DSN, |
| | SHARING_VIEW_ONLY_SECRET_TOKEN, |
| | SHARING_VIEW_ONLY_TOKEN_KEY_NAME |
+-----------------------+------------------------------------------------+
Finally, you can retrieve the environment variable of your interest like this:
divio app deployments get-var <deployment_uuid> <environment_variable_name>
Important
You must be an administrator of the respective application to retrieve this information.
Note
Setting environment variables is not currently supported using the Divio CLI.
See the Divio CLI command reference reference for more information.
Using the Control Panel#
Use the Env Variables view of an application to manage your custom environment variables.
Setting a custom environment variable with the same name as one of the built-in ones will overwrite it.
Important
In all cases, changes to environment variables will not apply until the environment is relaunched (redeployed on the cloud, or restarted locally).
Using a terminal session in a cloud container#
The env command will list all environment variables.
In the local environment#
By default, the .env-local file is used to store variables for the local
environment. See docker-compose.yml file.
env_file: .env-local
In the build phase#
Use ENV in the Dockerfile to set an environment variable that will be
used for the rest of the build process, and will also be baked into the image
and accessible at runtime.
ENV <key>=<value>
You can also force a particular command to run with a certain environment variable:
RUN <key>=<value> <command>
However, the environment variables with which cloud environments are provisioned (e.g. services such as databases and media storage) are not accessible at build time nor would it be desirable to rely on them in this phase, since the same image will be used in multiple cloud environments.
Additional information#
The PORT environment variable#
If the load balancer is unable to connect to the environment of an application within reasonable time during deployment, then the runtime logs should contain information such as:
A traceback revealing a programming error.
An application being too slow to start up in time.
A port number that could not be detected automatically.
If you suspect that the exposed port is not correctly detected, you can
configure an environment variable named PORT (e.g 8000) to manually
set the port number.
Leading and trailing spaces#
The Control Panel does not strip leading or trailing spaces from values. Be careful when pasting in values that you do not inadvertently include unwanted spaces.
If you get an unexpected error in your logs that includes a reference to an
environment variable value with a %20 character in it - that’s a sure sign
that it probably includes an undesired space.