Skip to content
Install

Manage variables and environments

Variables let you configure an app without rebuilding its image, so the same image can run with different settings in each environment. Set a variable on an app to configure that app. To reuse a value across apps, store it once as a shared variable in the environment and reference it from each app.

Saving variables restarts the app, because a process reads its environment at startup.

  1. Open the app.
  2. Go to Variables.
  3. Add the variables in Editor. To paste .env text, select Raw.
  4. Select Save.

An app can have up to 1,000 variables, and each value can be up to 64 KB. For files, use storage. For data, use a database.

A shared variable belongs to an environment. An app receives a shared value only when one of its own variables references it.

  1. Open the project.
  2. Go to Variables.
  3. Select the environment.
  4. In Shared variables, select Add variable.
  5. Enter the key and the value.
  6. Select Save.

Set an app variable to a reference:

API_BASE_URL=${{shared.API_BASE_URL}}

Orchard resolves references when it starts the pod and when it builds the image. If you change a shared value, Orchard updates and restarts only the apps whose values change.

Orchard encrypts secret values at rest. You can replace a secret value, but you cannot read it back from the dashboard, the CLI, the API, or MCP.

Orchard passes a secret to the container through the app’s Kubernetes Secret. The pod spec holds a reference and not the value.

To read a value from a database or another app, use a reference such as ${{resource.appdb.connection_string}}. To add one, select Use a resource in the value field. The available fields are listed in Connect an app to a database or app.

Each project has a Production environment by default. Each new environment gets its own namespace.

  1. Open the project.
  2. Open the environment menu.
  3. Select New environment.
  4. Enter a name.

To match a cluster environment during local development, pull its variables:

orchard env pull staging

The command writes the environment’s shared variables to .env.orchard. To change the path, use --out. To merge one app’s variables on top, use --deployment <id>.

Secret values are write-only, so the file contains commented placeholders for them. Fill these in locally.