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 as:

  • 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 (built-in).

Using the Control Panel#

Use the Env Variables view of an application to manage your custom environment variables.

'Managing environment variables'

Setting a custom environment variable with the same name as one of the built-in ones will overwrite it.

Divio environment variables also support pattern replacement, which means you can extend the value of one environment variable by referencing another. For more information and the rules that apply, see the pattern replacement section.

Important

In all cases, changes to environment variables will not apply until the environment is relaunched (redeployed on the cloud, or restarted locally).

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 as:

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. Once again, sensitive environment variables are not included at all in TXT format.

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 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#

Service environment variables#

Divio provides a number of services, such as databases and media storage, that can be used by your application’s environments. Each service has, potentially, their own set of environment variables, which are automatically set as built-in environment variables after the provisioning of the service and they are also prefixed with the unique service prefix.

Let’s take a look at the following example:

A postgres database with a prefix of DEFAULT has been provisioned for the test environment of your application. By visiting the Env Variables view, you will be able to notice that the Built-in section of the test environment has been updated with the following environment variables:

DEFAULT_DATABASE_DSN=postgres://<username>:<password>@<hostname>:<port>/<database_name>
DEFAULT_DATABASE_USERNAME=<username>
DEFAULT_DATABASE_PASSWORD=<password>
DEFAULT_DATABASE_HOSTNAME=<hostname>
DEFAULT_DATABASE_PORT=<port>
DEFAULT_DATABASE_DATABASE_NAME=<database_name>
...

Note

This is only a part of the environment variables that are automatically set after the provisioning of this service. The complete list depends on the service itself and could include additional ones. It is worth noting though that the DEFAULT_DATABASE_DSN could be constructed by using the rest of the environment variables. This is something that you can take advantage of in order to build up your own environment variables using the pattern replacement feature that Divio provides. For more information see the pattern replacement section below.

Pattern replacement#

Divio environment variables support pattern replacement, which means you can extend the value of one environment variable by referencing another. This allows you to build up complex values from simpler ones. For example, you could set a variable BASE_URL to https://example.com, and then reference it in another variable, such as SITE_URL:

BASE_URL=https://example.com
SITE_URL=$(BASE_URL)/index

The value of SITE_URL will now be https://example.com/index.

Setting environment variables is only supported in the Control Panel as of now. Start by typing the name of the variable you want to set and notice the Expand variable reference checkbox that appears below the value field. It is enabled by default and allows you to reference other environment variables right away. If you want to disable it, you can do so by unchecking the checkbox.

'Enabling environment variables pattern replacement in the Control Panel'

Although the whole process is faily straightforward, there are some rules that apply in order for the pattern replacement to work as expected. The complete set of rules, including the ones mentioned above, is as follows:

  • Enable the Expand variable reference checkbox.

  • Enclose the name of the referenced environment variable within a pattern replacement expression, e.g. $(BASE_URL).

  • The referenced environment variable must be defined before the one that references it. In other words, if BASE_URL (see example above) was defined after SITE_URL, the pattern replacement would not work and the value of SITE_URL would remain unchanged.

  • The referenced environment variable must be defined in the same environment.

Note

built-in environment variables can also be referenced by custom ones. Keep in mind though that if a built-in environment variable is overwritten by a custom one that conforms to the rules above, then the the latter will be used for pattern replacement.

Important

In all cases, changes to environment variables will not apply until the environment is relaunched (redeployed on the cloud, or restarted locally).

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.