Skip to main content
In this way, your app has additional information, such as database credentials, the host or port it can use, and which server to connect to.

​
Variable types

You can set variables at different levels. All variables can be strings or base64-encoded JSON-serialized values. The following table defines what types of variables are available to you:
TypeDefinerScopePrecedenceBuildRuntimeUses
ApplicationApplicationApplication4YesYesNon-secret values that are the same across all environments
ProjectUserProject3YesYesSecret values that are the same across all environments, such as database credentials
EnvironmentUserEnvironment2SomeYesValues that vary by environment, such as which database to connect to or which payment API keys to use
UpsunPre-definedEnvironment1SomeYesFor information about your Upsun project
If there are conflicts between variables with the same name, variables take precedence from 1 down. So Upsun-provided values (1) override environment variables (2), which override project variables (3), which override application-provided variables (4). All of the variables can also be overridden via a script.

​
Choosing a variable type

Choose how to set the variable based on what you are trying to do. Some environment variables should be the same for all environments. For example:
  • Build tool versions. If you have scripts that use specific versions of build tools (such as a specific Node.js version), You want the tools to be versioned along with your code so you can track the impact of changes. Set those variables in the application.
  • Credentials for common services. If you have credentials for services shared across your environments, you don’t want to commit these secrets to code. Set them as sensitive project variables.
Other configurations should vary between environment types. For example:
  • Service configuration for databases and such. This information be read from the service environment variables, or the Upsun-provided PLATFORM_RELATIONSHIPS variable. It varies by environment automatically.
  • Mode toggles such as enabling debug mode, disabling certain caches, and displaying more verbose errors. This information might vary by environment type and should be set on the environment level.
  • API keys for remote services, especially payment gateways. If you have a different payment gateway for production and for testing, set its keys on the environment level.

​
Overrides

If the names of variables at different levels match, an environment variable overrides a variable with the same name in a parent environment and both override a project variable. All variables can also be overridden via script. For an example of how the different levels work, suppose you have the following inheritable variables defined for the main environment: 
upsun var -e main
Variables on the project Example (abcdef123456), environment main:
+----------------+-------------+--------+---------+
| Name           | Level       | Value  | Enabled |
+----------------+-------------+--------+---------+
| system_name    | project     | Spiffy |         |
| system_version | project     | 1.5    |         |
| api_key        | environment | abc123 | true    |
| debug_mode     | environment | 1      | true    |
+----------------+-------------+--------+---------+
And the following variables defined for the feature-x environment, a child environment of main: 
upsun var -e feature-x
Variables on the project Example (abcdef123456), environment feature-x:
+----------------+-------------+--------+---------+
| Name           | Level       | Value  | Enabled |
+----------------+-------------+--------+---------+
| system_name    | project     | Spiffy |         |
| system_version | project     | 1.5    |         |
| api_key        | environment | def456 | true    |
| system_version | environment | 1.7    | true    |
+----------------+-------------+--------+---------+
In the main environment, you can access $PLATFORM_VARIABLES: 
echo $PLATFORM_VARIABLES | base64 --decode | jq
The output looks like this: 
{
    "system_name": "Spiffy",
    "system_version": "1.5",
    "api_key": "abc123",
    "debug_mode": "1"
}
While in the feature-x environment, it looks like this: 
{
    "system_name": "Spiffy",
    "system_version": "1.7",
    "api_key": "def456",
    "debug_mode": "1"
}
To get a visual overview of which variables are overridden in an environment, navigate in the Console to that environment’s variables settings. This example shows how it looks within the feature-x environment: