Skip to main content
Get a list of all variables defined on a given environment in the Console or use the CLI:
upsun var
You get output similar to the following:
Variables on the project Example (abcdef123456), environment main:
+------+---------+-------+---------+
| Name | Level   | Value | Enabled |
+------+---------+-------+---------+
| foo  | project | bar   | true    |
+------+---------+-------+---------+

Access variables in a shell

Project and environment variables with the prefix env: are available as Unix environment variables in all caps. Access these variables and Upsun-provided variables directly like this:
echo $FOO
bar
echo $PLATFORM_APPLICATION_NAME
Sample Project
Other project and environment variables are listed together in the PLATFORM_VARIABLES variable as a base64-encoded JSON object. Access them like this:
echo $PLATFORM_VARIABLES | base64 --decode
{"theanswer": "42"}
You can also get the value for a single variable within the array, such as with this command, which uses the jq processor:
echo $PLATFORM_VARIABLES | base64 --decode | jq '.theanswer'
"42"
Variable availability depends on the type and configuration. Variables available during builds can be accessed in build hooks and those available at runtime can be accessed in deploy hooks.

Access variables in your app

To access environment variables in your app, use a built-in method for the given language.
<?php

// A simple variable.
$projectId = getenv('PLATFORM_PROJECT');

// An encoded JSON object.
$variables = json_decode(base64_decode(getenv('PLATFORM_VARIABLES')), TRUE);

Access complex values

Variables can have nested structures. The following example shows nested structures in an app configuration: You can access these nested variables as follows:
echo $BASIC
a string
echo $INGREDIENTS
["peanut butter", "jelly"]
echo $QUANTITIES
{"cookies": "1 kg", "milk": "1 liter"}
echo "$PLATFORM_VARIABLES" | base64 --decode | jq '."stuff:STEPS"'
[
  "one",
  "two",
  "three"
]
echo "$PLATFORM_VARIABLES" | base64 --decode | jq '."stuff:COLORS"'
{
  "blue": "#0000FF",
  "green": "#00FF00",
  "red": "#FF0000"
}

Use provided variables

Upsun also provides a series of variables to inform your app about its runtime configuration. Many of them have a PLATFORM_ prefix to differentiate them from user-provided values. You can’t set or update them directly. The following table presents all available variables and whether they’re available at build time (during build hooks) and at runtime.
Variable nameBuildRuntimeDescription
CIYesNoAvailable for use in build scripts and tooling to modify build behavior (for example, to disable attempts to connect to other containers during the build phase, or to disable interactivity), which can help to reduce build failures.
PLATFORM_APP_COMMANDNoYesThe contents of the web start command.
PLATFORM_APP_DIRYesYesThe absolute path to the app directory.
PLATFORM_APPLICATIONYesYesA base64-encoded JSON object that describes the app. It maps certain attributes from your app configuration, some with more structure. See notes.
PLATFORM_APPLICATION_NAMEYesYesThe app name as set in your app configuration.
PLATFORM_BRANCHNoYesThe name of the Git branch.
PLATFORM_CACHE_DIRYesNoThe directory where files are cached from one build to the next. The directory is shared among all branches, so the same cache is used for all environments.
PLATFORM_DOCUMENT_ROOTNoYesThe absolute path to the web document root, if applicable.
PLATFORM_ENVIRONMENTNoYesThe name of the Upsun environment.
PLATFORM_ENVIRONMENT_TYPENoYesThe environment type of the Upsun environment (development, staging, or production).
PLATFORM_OUTPUT_DIRYesNoThe output directory for compiled languages at build time. Equivalent to PLATFORM_APP_DIR in most cases.
PLATFORM_POST_APP_COMMANDNoYesThe contents of the web post_start command.
PLATFORM_PRE_APP_COMMANDNoYesThe contents of the web pre_start command.
PLATFORM_PROJECTYesYesThe project ID.
PLATFORM_PROJECT_ENTROPYYesYesA random, 56-character value created at project creation and then stable throughout the project’s life. Can be used for Drupal hash salts, Symfony secrets, and other similar values.
PLATFORM_RELATIONSHIPSNoYesThe PLATFORM_RELATIONSHIPS variable is automatically broken down into service environment variables, so your app can seamlessly connect to databases and other services defined in .upsun/config.yaml.

For some advanced use cases, you may need to use the PLATFORM_RELATIONSHIPS variable itself. It is a base64-encoded JSON object of relationships, with keys that indicate the relationship names, and values that are arrays of relationship endpoint definitions. The exact format is defined differently for each service.
You may need to gather PLATFORM_RELATIONSHIPS information in a .environment file. See how to use .env files, and refer to dedicated service pages for examples.
PLATFORM_ROUTESNoYesA base64-encoded JSON object that describes the routes for the environment. It maps the content of your routes configuration. Note that this information is also available in your /run/config.json file.
PLATFORM_SMTP_HOSTNoYesThe SMTP host to send email messages through. Is empty when mail is disabled for the current environment.
PLATFORM_SOURCE_DIRYesNoThe path to the root directory of your code repository in the context of a running source operation. The directory contains a writable copy of your repository that you can commit to during the operation.
PLATFORM_TREE_IDYesYesThe ID of the tree the application was built from, essentially the SHA hash of the tree in Git. Use when you need a unique ID for each build.
PLATFORM_VARIABLESSomeSomeA base64-encoded JSON object with all user-defined project and environment variables that don’t use a prefix. The keys are the variable names and the values are the variable values. Availability during builds and at runtime depends on the settings for each variable. See how to access individual variables.
PLATFORM_VENDORYesNoAllows you to change the behavior of the build according to the vendor (Upsun or Platform.sh).
PORTNoYesA string representing the port to which requests are sent if the web.upstream.socket_family property is unset or set to tcp.
SOCKETNoYesA string representing the path to the Unix socket file to use if the web.upstream.socket_family property is set to unix.

PLATFORM_APPLICATION

The PLATFORM_APPLICATION variable is available both at build time and in the runtime environment. But the specific attributes it contains differ in each case. Each environment’s build is associated with a configuration ID that identifies it uniquely so builds can be reused. The ID is a product of your app code and some of its configuration for Upsun. Not every attribute your app configuration is relevant to the build. Only those attributes that are relevant to builds are accessible at build time from PLATFORM_APPLICATION. Attributes that are not available in PLATFORM_APPLICATION during builds:
  • Everything under access
  • Everything under relationship
  • Everything under firewall
  • hooks.deploy and hooks.post_deploy
  • Everything under crons
  • Everything under web, except web.mounts
  • Everything under workers, except workers.mounts
These attributes aren’t visible during build because they aren’t included as a part of the configuration component of the build slug. So modifying these values in your app configuration doesn’t trigger an app rebuild, only a redeploy. For more information, read about how builds work.

Use variables in static files

Some apps require configuration values to be specified in a static, non-executable file (such as a .ini, .xml, or .yaml file) and don’t support reading from environment variables. To populate these files with variables you set yourself, make sure the variables are set to be visible at build time. The files can’t be populated with Upsun-provided variables not available at build time (such as PLATFORM_RELATIONSHIPS or service environment variables). You also can’t write to them in a deploy hook as the file system is read only. One workaround is to create a symbolic link to a writable location and then write to it in a deploy hook. The following example shows the process, though you have to modify it to fit your needs.
  1. Create a mount that isn’t accessible to the web in your app configuration:
  1. Create a symbolic link from the config file the application wants to a location in that mount:
    # From the application root...
    
    ln -s config/db.yaml db.yaml
    
    This example assumes the app wants a db.yaml file in its root for configuration.
  2. Commit the symbolic link and an empty config directory to Git.
  3. Configure a script to read from environment variables and write to config/db.yaml through the service environment variables themselves, or through the PLATFORM_RELATIONSHIPS environment variable.
    Create a file with a shell script similar to this:
export-config.sh
   #!/bin/bash

   # Ensure the file is empty.
   cat '' > config/db.yaml

   # Map the database information from the service environment variable into the YAML file.
   # Use this process to use whatever variable names your app needs.
   # For more information, please visit https://docs.upsun.com/development/variables.html#service-environment-variables.

   printf "host: %s\n" $(echo $DATABASE_HOST) >> config/db.yaml
   printf "user: %s\n" $(echo $DATABASE_USERNAME) >> config/db.yaml
  1. Call the script from the deploy hook your app configuration:
Now, when your app starts and attempts to parse db.yaml, the symbolic link redirects it to config/db.yaml. Your script writes to that file on each deploy with updated information. Your app reads the exported values and proceeds as expected.
Last modified on March 11, 2026