> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Use variables
> See how to use variables that have already been set so you can take control over your app's environment.
export const DynamicCodeBlock = ({language = 'yaml', filename, icon, lines, wrap, expandable, highlight, focus, children}) => {
const STORAGE_KEY = 'upsun_versions_cache';
const COMPOSABLE_STORAGE_KEY = 'upsun_composable_cache';
const CACHE_TTL = 5 * 60 * 1000;
const API_URL = 'https://meta.upsun.com/images';
const COMPOSABLE_API_URL = 'https://meta.upsun.com/composable';
const DEBUG_PREFIX = '[DynamicCodeBlock cache]';
const [versionData, setVersionData] = useState(null);
const [versionError, setVersionError] = useState(false);
const [composableData, setComposableData] = useState(null);
const [composableError, setComposableError] = useState(false);
useEffect(() => {
const fetchData = async () => {
let cachedData = null;
let cachedEtag = null;
if (typeof localStorage !== 'undefined') {
try {
const cached = localStorage.getItem(STORAGE_KEY);
if (cached) {
const parsed = JSON.parse(cached);
cachedData = parsed?.data || null;
cachedEtag = parsed?.etag || null;
if (cachedData && Date.now() - parsed.timestamp < CACHE_TTL) {
return cachedData;
}
}
} catch (err) {
console.error('Failed to load from cache:', err);
}
}
const requestHeaders = cachedEtag ? {
'If-None-Match': cachedEtag
} : {};
console.debug(`${DEBUG_PREFIX} revalidating`, {
storageKey: STORAGE_KEY,
hasCachedData: Boolean(cachedData),
hasCachedEtag: Boolean(cachedEtag)
});
const response = await fetch(API_URL, {
headers: requestHeaders
});
if (response.status === 304 && cachedData) {
console.debug(`${DEBUG_PREFIX} revalidated (304)`, {
storageKey: STORAGE_KEY
});
if (typeof localStorage !== 'undefined') {
try {
const etag = response.headers.get('etag') || cachedEtag;
localStorage.setItem(STORAGE_KEY, JSON.stringify({
data: cachedData,
etag,
timestamp: Date.now()
}));
} catch (err) {
console.error('Failed to refresh cache metadata:', err);
}
}
return cachedData;
}
if (!response.ok) throw new Error(`API request failed: ${response.statusText}`);
const data = await response.json();
const etag = response.headers.get('etag');
console.debug(`${DEBUG_PREFIX} refreshed (200)`, {
storageKey: STORAGE_KEY,
etag
});
if (typeof localStorage !== 'undefined') {
try {
localStorage.setItem(STORAGE_KEY, JSON.stringify({
data,
etag,
timestamp: Date.now()
}));
} catch (err) {
console.error('Failed to cache data:', err);
}
}
return data;
};
fetchData().then(data => setVersionData(data)).catch(err => console.error('Failed to fetch version data:', err));
}, []);
const findHighestVersion = versionsMap => {
if (!versionsMap || Object.keys(versionsMap).length === 0) return null;
const entries = Object.entries(versionsMap);
const active = entries.filter(([, v]) => v.upsun && v.upsun.status === 'supported' || v.upsun && v.upsun.status === 'deprecated');
const candidates = active.length > 0 ? active : entries;
let [highestName] = candidates[0];
for (let i = 1; i < candidates.length; i++) {
const [currentName] = candidates[i];
const cp = currentName.split('.').map(Number);
const hp = highestName.split('.').map(Number);
for (let j = 0; j < Math.max(cp.length, hp.length); j++) {
if ((cp[j] || 0) > (hp[j] || 0)) {
highestName = currentName;
break;
} else if ((cp[j] || 0) < (hp[j] || 0)) {
break;
}
}
}
return highestName;
};
const getVersion = (lang, requestedVersion = 'latest') => {
if (lang === 'composable') {
if (!composableData || !composableData.versions || Object.keys(composableData.versions).length === 0) return null;
if (requestedVersion && requestedVersion !== 'latest') {
return (requestedVersion in composableData.versions) ? requestedVersion : null;
}
return findHighestVersion(composableData.versions);
}
if (!versionData) return null;
const imageData = versionData[lang];
if (!imageData || !imageData.versions || Object.keys(imageData.versions).length === 0) {
return null;
}
if (requestedVersion && requestedVersion !== 'latest') {
return (requestedVersion in imageData.versions) ? requestedVersion : null;
}
return findHighestVersion(imageData.versions);
};
let code = typeof children === 'string' ? children : String(children || '');
const codeLines = code.split('\n');
while (codeLines.length > 0 && codeLines[0].trim() === '') codeLines.shift();
while (codeLines.length > 0 && codeLines[codeLines.length - 1].trim() === '') codeLines.pop();
if (codeLines.length > 0) {
const indents = codeLines.filter(line => line.trim().length > 0).map(line => line.match(/^[ \t]*/)[0].length);
const minIndent = Math.min(...indents);
code = codeLines.map(line => line.slice(minIndent)).join('\n');
}
code = code.replace(/\{\{version:(.*?)\}\}/g, (match, params) => {
const parts = params.split(':');
const lang = parts[0];
const ver = parts[1] || 'latest';
const isComposable = lang === 'composable';
const hasError = isComposable ? composableError : versionError;
const dataReady = isComposable ? composableData !== null : versionData !== null;
if (hasError) return '(unavailable)';
if (dataReady) {
const resolvedVersion = getVersion(lang, ver);
return resolvedVersion || match;
}
return '...';
});
const codeBlockProps = {
language,
...filename && ({
filename
}),
...icon && ({
icon
}),
...lines !== undefined && ({
lines
}),
...wrap !== undefined && ({
wrap
}),
...expandable !== undefined && ({
expandable
}),
...highlight && ({
highlight
}),
...focus && ({
focus
})
};
return {code};
};
Get a list of all variables defined on a given environment in [the Console](/docs/administration/web/configure-environment#variables)
or use the CLI:
```bash theme={null}
upsun var
```
You get output similar to the following:
```bash theme={null}
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](/docs/development/variables#top-level-environment-variables) `env:`
are available as Unix environment variables in all caps.
Access these variables and Upsun-provided variables directly like this:
```bash theme={null}
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:
```bash theme={null}
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](https://stedolan.github.io/jq/):
```bash theme={null}
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: The [`getenv()` function](https://www.php.net/manual/en/function.getenv.php)
* Python: The [`os.environ` object](https://docs.python.org/3/library/os.html#os.environ)
* Node.js: The [`process.env` object](https://nodejs.org/api/process.html#process_process_env)
* Ruby: The [`ENV` accessor](https://docs.ruby-lang.org/en/master/ENV.html)
* Java: The [`System.getenv()` method](https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#getenv-java.lang.String-)
```php theme={null}
```python theme={null}
import os
import json
import base64
# A simple variable.
project_id = os.getenv('PLATFORM_PROJECT')
# An encoded JSON object.
variables = json.loads(base64.b64decode(os.getenv('PLATFORM_VARIABLES')).decode('utf-8'))
```
```js theme={null}
const { env } = process;
// Utility to assist in decoding a packed JSON variable.
function read_base64_json(varName) {
try {
return JSON.parse(Buffer.from(env[varName], "base64").toString());
} catch (err) {
throw new Error(`no ${varName} environment variable`);
}
};
// A simple variable.
const projectId = env.PLATFORM_PROJECT;
// An encoded JSON object.
const variables = read_base64_json('PLATFORM_VARIABLES');
```
```ruby theme={null}
# A simple variable.
project_id = ENV["PLATFORM_PROJECT"] || nil
# An encoded JSON object.
variables = JSON.parse(Base64.decode64(ENV["PLATFORM_VARIABLES"]))
```
```java theme={null}
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.util.Base64;
import java.util.Map;
import static java.lang.System.getenv;
import static java.util.Base64.getDecoder;
public class App {
public static void main(String[] args) throws IOException {
// A simple variable.
final String project = getenv("PLATFORM_PROJECT");
// An encoded JSON object.
ObjectMapper mapper = new ObjectMapper();
final Map variables = mapper.readValue(
String.valueOf(getDecoder().decode(getenv("PLATFORM_VARIABLES"))), Map.class);
}
}
```
### Access complex values
Variables can have nested structures.
The following example shows nested structures in an [app configuration](/docs/configure-apps/image-properties/variables):
{`
applications:
:
variables:
env:
BASIC: "a string"
INGREDIENTS:
- 'peanut butter'
- 'jelly'
QUANTITIES:
"milk": "1 liter"
"cookies": "1 kg"
stuff:
STEPS: ['one', 'two', 'three']
COLORS:
red: '#FF0000'
green: '#00FF00'
blue: '#0000FF'`
}
You can access these nested variables as follows:
```bash theme={null}
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"
}
```
```php theme={null}
string(2) "one"
[1]=>
string(4) "two"
[2]=>
string(5) "three"
}
*/
print_r($variables['stuff:COLORS']);
/*
array(3) {
["red"]=>
string(7) "#FF0000"
["green"]=>
string(7) "#00FF00"
["blue"]=>
string(7) "#0000FF"
}
*/
```
```python theme={null}
import os
import json
import base64
print os.getenv('BASIC')
# a string
print os.getenv('INGREDIENTS')
# ["peanut butter", "jelly"]
print os.getenv('QUANTITIES')
# {"milk": "1 liter", "cookies": "1 kg"}
variables = json.loads(base64.b64decode(os.getenv('PLATFORM_VARIABLES')).decode('utf-8'))
print variables['stuff:STEPS']
# [u'one', u'two', u'three']
print variables['stuff:COLORS']
# {u'blue': u'#0000FF', u'green': u'#00FF00', u'red': u'#FF0000'}
```
```java theme={null}
scriptconst { BASIC, INGREDIENTS, QUANTITIES, PLATFORM_VARIABLES } = process.env;
const { "stuff:STEPS": stuffSteps, "stuff:COLORS": stuffColors } = JSON.parse(
Buffer.from(PLATFORM_VARIABLES, "base64").toString()
);
console.log(BASIC);
// "a string"
console.log(INGREDIENTS);
// ["peanut butter", "jelly"]
console.log(QUANTITIES);
// {"cookies": "1 kg", "milk": "1 liter"}
console.log(stuffSteps);
// [ 'one', 'two', 'three' ]
console.log(stuffColors);
// { 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](/docs/configure-apps/hooks/hooks-comparison#build-hook))
and at runtime.
| Variable name | Build | Runtime | Description |
| --------------------------- | ----- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CI` | Yes | No | Available 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_COMMAND` | No | Yes | The contents of the [web start command](/docs/configure-apps/image-properties/web#web-commands). |
| `PLATFORM_APP_DIR` | Yes | Yes | The absolute path to the app directory. |
| `PLATFORM_APPLICATION` | Yes | Yes | A base64-encoded JSON object that describes the app. It maps certain attributes from your [app configuration](/docs/configure-apps), some with more structure. See [notes](#platform_application). |
| `PLATFORM_APPLICATION_NAME` | Yes | Yes | The app name as set in your [app configuration](/docs/configure-apps). |
| `PLATFORM_BRANCH` | No | Yes | The name of the Git branch. |
| `PLATFORM_CACHE_DIR` | Yes | No | The 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_ROOT` | No | Yes | The absolute path to the web document root, if applicable. |
| `PLATFORM_ENVIRONMENT` | No | Yes | The name of the Upsun environment. |
| `PLATFORM_ENVIRONMENT_TYPE` | No | Yes | The environment type of the Upsun environment (`development`, `staging`, or `production`). |
| `PLATFORM_OUTPUT_DIR` | Yes | No | The output directory for compiled languages at build time. Equivalent to `PLATFORM_APP_DIR` in most cases. |
| `PLATFORM_POST_APP_COMMAND` | No | Yes | The contents of the [web post\_start command](/docs/configure-apps/image-properties/web#web-commands). |
| `PLATFORM_PRE_APP_COMMAND` | No | Yes | The contents of the [web pre\_start command](/docs/configure-apps/image-properties/web#web-commands). |
| `PLATFORM_PROJECT` | Yes | Yes | The project ID. |
| `PLATFORM_PROJECT_ENTROPY` | Yes | Yes | A 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_RELATIONSHIPS` | No | Yes | The `PLATFORM_RELATIONSHIPS` variable is automatically broken down into [service environment variables](/docs/development/variables#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](/docs/add-services).
You may need to gather `PLATFORM_RELATIONSHIPS` information in a `.environment` file. See how to [use `.env` files](/docs/development/variables/set-variables#when-to-use-env-files), and refer to [dedicated service pages](/docs/add-services) for examples. |
| `PLATFORM_ROUTES` | No | Yes | A base64-encoded JSON object that describes the routes for the environment. It maps the content of your [routes configuration](/docs/routes). Note that this information is also available in your `/run/config.json` file. |
| `PLATFORM_SMTP_HOST` | No | Yes | The SMTP host to send email messages through. Is empty when mail is disabled for the current environment. |
| `PLATFORM_SOURCE_DIR` | Yes | No | The path to the root directory of your code repository in the context of a running [source operation](/docs/configure-apps/source-operations). The directory contains a writable copy of your repository that you can commit to during the operation. |
| `PLATFORM_TREE_ID` | Yes | Yes | The 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_VARIABLES` | Some | Some | A base64-encoded JSON object with all user-defined project and environment variables that don't use a [prefix](/docs/development/variables#variable-prefixes). 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](#access-variables-in-a-shell). |
| `PLATFORM_VENDOR` | Yes | No | Allows you to change the behavior of the build according to the vendor (Upsun or Platform.sh). |
| `PORT` | No | Yes | A `string` representing the port to which requests are sent if the [`web.upstream.socket_family` property](/docs/configure-apps/image-properties/web#upstream) is unset or set to `tcp`. |
| `SOCKET` | No | Yes | A `string` representing the path to the Unix socket file to use if the [`web.upstream.socket_family` property](/docs/configure-apps/image-properties/web#upstream) 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](/docs/configure-apps).
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`
* `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](/docs/configure-apps) doesn't trigger an app rebuild, only a redeploy.
For more information, read about [how builds work](/docs/core-concepts/build-deploy#the-build).
## 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](/docs/development/variables/set-variables#variable-options).
The files can't be populated with Upsun-provided variables not available at build time (such as `PLATFORM_RELATIONSHIPS` or [service environment variables](/docs/development/variables#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](/docs/configure-apps/hooks/hooks-comparison#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](/docs/configure-apps):
{`
applications:
mounts:
/config:
source: storage
source_path: config`
}
2. Create a symbolic link from the config file the application wants to a location in that mount:
```bash theme={null}
# 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.
3. Commit the symbolic link and an empty `config` directory to Git.
4. Configure a script to read from environment variables and write to `config/db.yaml` through the [service environment variables](/docs/development/variables#service-environment-variables) themselves, or through the [`PLATFORM_RELATIONSHIPS` environment variable](/docs/development/variables/use-variables#use-provided-variables).
Create a file with a shell script similar to this:
```bash export-config.sh theme={null}
#!/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 /docs/development/variables#service-environment-variables.
printf "host: %s\n" $(echo $DATABASE_HOST) >> config/db.yaml
printf "user: %s\n" $(echo $DATABASE_USERNAME) >> config/db.yaml
```
```bash export-config.sh theme={null}
#!/bin/bash
# Ensure the file is empty.
cat '' > config/db.yaml
# Map the database information from the PLATFORM_RELATIONSHIPS variable into the YAML file.
# Use this process to use whatever variable names your app needs.
# For more information, please visit /docs/development/variables/use-variables#use-provided-variables.
printf "host: %s\n" $(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".database[0].host") >> config/db.yaml
printf "user: %s\n" $(echo $PLATFORM_RELATIONSHIPS | base64 --decode | jq -r ".database[0].username") >> config/db.yaml
```
5. Call the script from the `deploy` hook your [app configuration](/docs/configure-apps):
{`
applications:
hooks:
deploy: |
bash export-config.sh`
}
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.