.. meta:: :description: Find Divio's how-to guide to managing an app’s environment variables. Your app relies on these to config app settings and access to storage, database and more. .. _manage-environment-variables: 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). .. seealso:: * :ref:`Environment variables reference ` .. _reading-env-vars: Using the Control Panel ^^^^^^^^^^^^^^^^^^^^^^^ Use the **Env Variables** view of an application to manage your custom environment variables. .. image:: /images/control-panel-environment-variables.png :alt: '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 :ref:`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): .. code-block:: bash divio app environment-variables list Output: .. code-block:: bash Environment: test () +--------------------+------------------+----------------+ | 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: .. code-block:: bash divio app environment-variables --json list Output: .. code-block:: json [ { "environment": "test", "environment_uuid": "", "environment_variables": [ { "uuid": "", "name": "SIMPLE_VAR_NAME", "value": "SIMPLE VAR VALUE", "order": 1, "is_sensitive": false, "is_read_only": false }, { "uuid": "", "name": "SENSITIVE_VAR_NAME", "order": 2, "is_sensitive": true, "is_read_only": false } ] } ] Or: .. code-block:: bash divio app environment-variables --txt list Output: .. code-block:: bash Environment: test () -------------------------------------- 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: .. code-block:: bash divio app environment-variables list -e live Retrieve custom environment variables across all environments of an application using the ``--all-envs`` flag: .. code-block:: bash divio app environment-variables list --all-envs Retrieve a specific custom environment variable from the default cloud environment (test): .. code-block:: bash divio app environment-variables get SIMPLE_VAR_NAME Output: .. code-block:: bash Environment: test () +--------------------+------------------+----------------+ | 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: .. code-block:: bash divio app environment-variables get SIMPLE_VAR_NAME --all-envs .. _how-to-retrieve-built-in-env-vars: .. 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. .. code-block:: bash divio app deployments list -e live Output: .. code-block:: bash Environment: live () +-------------------+---------------+-----------------------------+-----------------------------+----------------------+ | uuid | author | started_at | ended_at | status | success | +===================+===============+=============================+=============================+==========+===========+ | | | 2023-02-14T10:35:43.609956Z | 2023-02-14T10:36:54.635565Z | done | True | +-------------------+---------------+-----------------------------+-----------------------------+----------+-----------+ | | | 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). .. code-block:: bash divio app deployments get Output: .. code-block:: bash Environment: test () +-----------------------+------------------------------------------------+ | uuid | | +-----------------------+------------------------------------------------+ | author | | +-----------------------+------------------------------------------------+ | 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: .. code-block:: bash divio app deployments get-var .. 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 :ref:`divio-cli-command-ref` 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. .. code-block:: bash env_file: .env-local .. _setting-env-vars-build: 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. .. code-block:: dockerfile ENV = You can also force a particular command to run with a certain environment variable: .. code-block:: dockerfile RUN = 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: .. code-block:: bash DEFAULT_DATABASE_DSN=postgres://:@:/ DEFAULT_DATABASE_USERNAME= DEFAULT_DATABASE_PASSWORD= DEFAULT_DATABASE_HOSTNAME= DEFAULT_DATABASE_PORT= DEFAULT_DATABASE_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 :ref:`pattern replacement ` section below. .. _env-vars-pattern-replacement: 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``: .. code-block:: bash 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. .. image:: /images/control-panel-environment-variables-enable-pattern-replacement.png :alt: '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). .. _env-var-port: 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.