# Set environment variables

Give an app plain variables and secrets by reference, and roll the change out with or without a redeploy.

A variable is either a plain value or a reference to a secret from **Secrets**. A secret's value is
decrypted at deployment and handed to the machine, never stored on the app. An app holds up to 1000
variables, each value at most 8192 characters. Replace app-id with the app's id and
secret-id with a secret's id.

## Prerequisites

- Permission for `deploy:ManageEnv` on the app. To bind a secret, `secrets:GetSecretValue` on it;
  binding grants it to the `deploy` consumer. To redeploy in the same step, `deploy:DeployApp`.
- In the console, also `deploy:DescribeApp` to open the app's page (without it the page is not
  found).

## Set the variables

**Console**
1. Open the app's **Environment** tab.
2. Choose **Add variable**.
3. In the new row, enter the variable name.
4. Choose **Value** and enter the value, or choose **Secret** and, under **Choose a secret…**,
   choose the secret.
5. Choose **Save environment**, or **Save & redeploy** (shown only with `deploy:DeployApp`) to roll
   the change out at once.

**CLI**
```sh
dcloud deploy env replace app-id \
  --vars '{"key":"LOG_LEVEL","valueKind":"plain","plainValue":"info"}' \
  --vars '{"key":"API_TOKEN","valueKind":"secret","kmsSecretId":"secret-id"}' \
  --redeploy
```

**API**
```http
PUT /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/env
{
  "vars": [
    { "key": "LOG_LEVEL", "valueKind": "plain", "plainValue": "info" },
    { "key": "API_TOKEN", "valueKind": "secret", "kmsSecretId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a" }
  ],
  "redeploy": true
}
```

The call replaces the whole environment.

**Terraform**
```hcl
resource "dcloud_app_env" "web" {
  app_id = dcloud_app.web.id
  vars = {
    LOG_LEVEL = "info"
  }
  secret_vars = {
    API_TOKEN = dcloud_secret.api_token.id
  }
  redeploy = true
}
```

The resource owns every variable: a variable set elsewhere is removed on the next apply, and
destroying it empties the environment.

## Saving does not restart the app

The running container keeps the environment it started with. **Save & redeploy**, or
`"redeploy": true` on any environment write, rolls the change out; without it, the panel shows
**Saved, not running.** and what changed until someone redeploys. Choose **Redeploy now** on that
banner, or:

```sh
dcloud deploy redeploy apply app-id --reason "New LOG_LEVEL"
```

The banner, and `status` in `GET /deploy/api/apps/app-id/env`, report the app as behind
when the environment was saved after the live deployment started, or a bound secret (a database
binding's included) changed since, including one synced from 1Password. An app with no live
deployment is never reported as behind.

A redeploy (from an environment change, an import, a database binding, a credential rotation or
**Redeploy now**) creates a deployment that runs exactly what the **live** deployment runs: the
same image, or the same pinned compose file. Nothing is rebuilt: an app built from a repository
reuses the live image by its digest, and is rebuilt from the same commit only when that image is no
longer in its registry repository (the deployment's activity says which). A configuration change is
never also a code change. An app with no live deployment yet has nothing to reuse: its redeploy
builds or pulls the current source. A redeploy needs `deploy:DeployApp` as well as the write itself.

## What the containers receive

The machine hands the variables to the container in a file, so a long list costs nothing at start.
A plain value cannot contain a line break: it is refused with `400` "A value cannot contain a line
break, so bind a secret for multi-line material". A secret's value with line breaks (a PEM key, a
service-account JSON) reaches the container intact as an ordinary environment variable, so bring
such a value in as a secret (`op://…`, or a secret created in **Secrets**). For a compose app, which services receive which variables is in
[Compose files](compose-files.md#the-environment-of-each-service).

Scheduled jobs get the environment as of the live deployment: a variable saved without
redeploying reaches jobs when it reaches the app.

## Result

After the redeploy, the app's containers start with the new environment. The **Environment** tab
also lists **Secrets this app uses**: where each value comes from, and the version the app last
read.

## Related

- [Import a .env file](import-a-env-file.md)
- [Bind a managed database](bind-a-database.md)
- `deploy.env.replace` · `dcloud deploy env replace` · `dcloud_app_env`
