Environment Variables

Qovery supports environment variables to make you able to configure your applications.

Environment Variables are not directly connected to Environment concept.

• Environment Variables: represent variables you can store and retrieve in your applications
• Environments: represent environments (apps, databases, and other services) associated with Git branches like master, staging, and others.

Levels

There are four levels of Environment Variables. Each type differs in scope - you can create variables bound to application, environment, or project.

Scope	Level	Description
BUILT_IN	1	Automatically generated variables based on your configuration (e.g., requested databases) propagated to all projects, environments, and applications
PROJECT	2	Variables at the project level are shared across all environments and all applications of the project
ENVIRONMENT	3	Variables at the environment level are shared across all applications of the project in one, given environment
APPLICATION	4	Variables available for one application in one environment

You can override variables - the highest level variable win (e.g., PROJECT variable can override BUILT_IN variable).

Built-in variables

By default, every environment contains those variables:

Name	Example	Description
QOVEY_JSON_B64	-	Contains all environment variables accessible by your application encoded as Base64 JSON
QOVERY_BRANCH_NAME	master	Git branch name
QOVERY_IS_PRODUCTION	true	Flag that indicates production environment

Additional built-in variables

For any added service (database, broker, storage), your application receives additional built-in variables. These can be used, for example, to connect to the database.

Naming Convention:

We use the following naming convention for additional built-in variables:

QOVERY_<SERVICE_TYPE>_<NAME>_<SPEC>

To demonstrate this, let's take a quick look on a simple database example:

.qovery.yml

application:
  ...
databases:
- type: postgresql
  version: "10.10"
  name: my-pg

Adding a database like in the example above results in adding the following environment variables to your application:

Name	Example	Description
QOVERY_DATABASE_MY_PG_NAME	my-postgresql	Name of your PostgreSQL database
QOVERY_DATABASE_MY_PG_HOST	host.amazonaws.com	PostgreSQL host address
QOVERY_DATABASE_MY_PG_USERNAME	username	PostgreSQL username
QOVERY_DATABASE_MY_PG_PASSWORD	password	PostgreSQL password
...	...	...

Add custom variables

Adding environment variables with the CLI is very simple:

qovery project env add ENV_NAME ENV_VALUE
qovery environment env add ENV_NAME ENV_VALUE
qovery application env add ENV_NAME ENV_VALUE

When you add Environment Variables using the CLI, you also specify the scope of a given variable, e.g.

qovery project env add ENV_NAME ENV_VALUE
qovery environment env add ENV_NAME ENV_VALUE
qovery application env add ENV_NAME ENV_VALUE

The highlighted command adds a variable with environment scope.

Qovery CLI is aware of your current directory and Git branch. Be sure you are in the correct application directory and Git branch (environment) before executing Qovery Environment Variables commands.

List variables

You can list environment variables of given application with single CLI command:

qovery application env list

OUTPUT

SCOPE        KEY                                                   VALUE
BUILT_IN     QOVERY_BRANCH_NAME                                    feature_a
BUILT_IN     QOVERY_IS_PRODUCTION                                  false
BUILT_IN     QOVERY_DATABASE_MY_POSTGRESQL_3498225_PASSWORD        xxxxxxxxxxxxxxxxxxxx
BUILT_IN     QOVERY_DATABASE_MY_POSTGRESQL_3498225_USERNAME        superuser
BUILT_IN     QOVERY_DATABASE_MY_POSTGRESQL_3498225_PORT            5432
BUILT_IN     QOVERY_DATABASE_MY_POSTGRESQL_3498225_FQDN            your.fqdn.id.rds.amazonaws.com
BUILT_IN     QOVERY_DATABASE_MY_POSTGRESQL_3498225_HOST            your.host.id.rds.amazonaws.com
BUILT_IN     QOVERY_DATABASE_MY_POSTGRESQL_3498225_CONNECTION_URI  postgresql://user:[email protected]:5432/postgres
BUILT_IN     QOVERY_DATABASE_MY_POSTGRESQL_3498225_VERSION         11.5
BUILT_IN     QOVERY_DATABASE_MY_POSTGRESQL_3498225_TYPE            POSTGRESQL
BUILT_IN     QOVERY_DATABASE_MY_POSTGRESQL_3498225_NAME            my-postgresql-id
PROJECT      my_custom_project_env                                 my_project_value
ENVIRONMENT  DRY_RUN                                               true
APPLICATION  enable_feature_a                                      true

Analogically to adding environment variables, while listing Environment Variables you also choose the scope of variables to list:

qovery application env list
qovery project env list
qovery environment env list

Delete variables

To delete an environment variable of application scope, run:

qovery application env delete MY_ENV_NAME

You can not delete BUILT_IN variables, but you can override them!

Override variables

As described in the levels' section, you can override existing variables. To do so, add a new Environment Variables with a higher level (e.g., add an APPLICATION level variable to override PROJECT variable for a given application).

Aliases

You can create an alias for the existing environment variable.

Let's suppose that your application requires a DATABASE_PASSWORD variable. Qovery provides your application with QOVERY_DATABASE_MY_POSTGRESQL_3498225_PASSWORD variable with a database password. Instead of copy-pasting its value, you can create an alias to QOVERY_DATABASE_MY_POSTGRESQL_3498225_PASSWORD.

qovery application env add DATABASE_PASSWORD '$QOVERY_DATABASE_MY_POSTGRESQL_3498225_PASSWORD'

After executing the above command, your application can use DATABASE_PASSWORD variable to get a database password.

The syntax for aliasing is:

... add NEW_VARIABLE_NAME `$OLD_VARIABLE_NAME`

.env file (dot env file)

When running your application, you will typically use a set of environment variables to capture the configuration of the application. For example: say your app uses a logger to debug what's going on. You would want to put your logger in debug mode.

The .env file lets you capture all the environment variables that you need in order to run your application locally. When you start your application using qovery run, the .env file is read, and each name/value pair is inserted into the environment, to mimic the action of environment variables.

View you application's environment variables

To view all of your application’s environment variables, type qovery application env list.

Look at the contents of your .env file

$ cat .env

Here's an example .env file:

LOGGER=debug
MY_VAR_2=myValue2

Add an environment variable to your .env file

To add an environment variable to your .env file, edit it and add a new name=value pair on a new line.

Copy Qovery environment variables to your local .env file

Sometimes you may want to use the same environment variable in both local and Qovery environments. For each environment variable that you want to add to your .env file, use the following command:

$ qovery application env list --dotenv >> .env

If you want to export the environment variables with secrets you can add -c

$ qovery application env list -c --dotenv >> .env

Policies

• Environment variable keys should use only alphanumeric characters, and the underscore character (_) to ensure that they are accessible from all programming languages. Environment variable keys should not include the hyphen character.
• Environment variable keys should not begin with a double underscore (__).
• An environment variable’s key should not begin with QOVERY_ unless it is set by the Qovery platform itself.