Environment variables

In Divio, environment variables provide a powerful and flexible way to manage configuration information in your applications in the cloud and your local machine.

This functionality allows you to store sensitive information, such as passwords and API keys, outside your codebase and keep it secure.

Managing environment variables

Introduction

In Divio cloud applications, environment variables define and configure specific settings or parameters for an application's environment.

When an application is provisioned, environment variables specific to the environment are also automatically provisioned. Additionally, when a service is provisioned, such as a database, or an object storage, corresponding environment variables are also provisioned. Refer to the environment variables reference for a list of BUILT-IN environment variables.

Environment variables are displayed on the Env Variables view.

Deployment Required

After adding or changing environment variables, the respective environment must be redeployed to apply the configuration.

Types

Your application relies on environment variables to configure its settings and 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 are automatically set by our infrastructure.
Custom environment variables are user-configurable and can also be used to overwrite environment variables of the previous category (built-in).

Environment Variables inside Dockerfile

We do not support the use of environment variables in the Dockerfile, as they are not available at build time due to security reasons. The ENV statement can be used for some configuration, but secrets should only be read by the application at runtime. This follows the Twelve-Factor principles.

Usage

It's important to note that environment variables should only apply to environments, not states or processes independent of a particular environment.

Your application should not be subject to any particular environment conditions during the build phase.

Here are some examples of how to integrate environment variables into your application:

// access environment variables
const DATABASE_URL = process.env.DATABASE_URL;
const SECRET_KEY = process.env.SECRET_KEY;
const DEBUG = process.env.DEBUG === 'True';

# access environment variables
DATABASE_URL = os.environ.get('DATABASE_URL')
SECRET_KEY = os.environ.get('SECRET_KEY')
DEBUG = os.environ.get('DEBUG', 'False') == 'True'

// access environment variables
$DATABASE_URL = getenv('DATABASE_URL');
$SECRET_KEY = getenv('SECRET_KEY');
$DEBUG = getenv('DEBUG') === 'True';

// access environment variables
String DATABASE_URL = System.getenv("DATABASE_URL");
String SECRET_KEY = System.getenv("SECRET_KEY");
boolean DEBUG = Boolean.parseBoolean(System.getenv("DEBUG"));

// access environment variables
string DATABASE_URL = Environment.GetEnvironmentVariable("DATABASE_URL");
string SECRET_KEY = Environment.GetEnvironmentVariable("SECRET_KEY");
bool DEBUG = bool.Parse(Environment.GetEnvironmentVariable("DEBUG") ?? "False");

# access environment variables
DATABASE_URL = ENV["DATABASE_URL"]
SECRET_KEY = ENV["SECRET_KEY"]
DEBUG = ENV["DEBUG"] == "True"

// access environment variables
DATABASE_URL := os.Getenv("DATABASE_URL")
SECRET_KEY := os.Getenv("SECRET_KEY")
DEBUG, _ := strconv.ParseBool(os.Getenv("DEBUG"))

Built-in variables

Built-in variables are automatically provided to each environment. They can be overridden by custom variables with varying degrees of sensitivity, such as hidden-valued environment variables.

Some of the most note-worthy built-in environment variables are:

DATABASE_URL, <prefix>_DATABASE_DSN: Each database provisioned in Services will have a corresponding environment variable, for example DEFAULT_DATABASE_DSN (depending on the prefix applied - the default prefix is always DEFAULT). The DEFAULT_DATABASE_DSN is also exposed as DATABASE_URL
DOMAIN: The primary domain of the environment's server.
DOMAIN_ALIASES: Other domains for the environment, separated by commas.
GIT_BRANCH: The cloud environment's Git branch.
SECRET_KEY: A generated random key that your application can use as a unique identifier for internal security purposes.
STAGE: The name of the environment (test, live, etc).
<prefix>_STORAGE_DSN: Each object storage provisioned in Services will have a corresponding environment variable, for example DEFAULT_STORAGE_DSN (depending on the prefix applied - the default prefix is always DEFAULT).

Accessing environment variables

You can access the values of any environment variable by SSHing into the container of the environment and echoing the value. Depending on your Docker configuration this might look something like this:

echo $DATABASE_URL

You can find the SSH command on the dashboard of your application.

Local environment

In addition to cloud applications, your local application also uses environment variables, which can be configured in a file called .env-local specified in the docker-compose.yml file.

To adapt your docker-compose.yml file to use environment variables, you can use the following example:

services:
  web:
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - SECRET_KEY=${SECRET_KEY}
      - DEBUG=${DEBUG}

or use a .env-local file:

services:
  web:
    env_file:
      - .env-local

and within the .env-local file:

DATABASE_URL=postgres://user:password@localhost:5432/dbname
SECRET_KEY=your_secret_key
DEBUG=True

Using the Divio CLI

The Divio CLI allows you to retrieve environment variables from the command line:

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

info

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

info

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>

info

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

You can also force a particular command to run with a certain environment variable:

ENV NPM_VERSION=latest

RUN npm install -g npm@$NPM_VERSION

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 can be used in multiple cloud environments.

Additional information

Service environment variables

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

info

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 fairly 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.

info

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 application 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.

Was this helpful?

Share Your Thoughts

Introduction​

Types

Usage​

Built-in variables​

Accessing environment variables​

Local environment​

Using the Divio CLI​

Using a terminal session in a cloud container​

In the build phase​

Additional information​

Service environment variables​

Pattern replacement​

The PORT environment variable​

Leading and trailing spaces​

Introduction

Usage

Built-in variables

Accessing environment variables

Local environment

Using the Divio CLI

Using a terminal session in a cloud container

In the build phase

Additional information

Service environment variables

Pattern replacement

The `PORT` environment variable

Leading and trailing spaces