Development

Configuring Environment Variables

Applies to
Gateway+Developer Portal
Hosting
Managed EdgeManaged DedicatedDiffersSelf-Hosted
1 difference by hosting option
Managed Dedicated

Working copy environments aren't available, so the Development (Working Copy) option doesn't apply. Use a .env file for local development instead.

Environment variables are key-value pairs that are stored outside of source code. Set a different value for each environment to change behavior or configuration without changing code.

Variables are only applied to environments on new deployments. If you change an environment variable, redeploy the environment for the updated value to take effect.

Environment variables can be configuration or secrets. All values are stored encrypted at rest, but only configuration values can be read back. Secrets are write-only: you can't retrieve a secret's value after you set it.

Gateway and Developer Portal Variables

A Zuplo project has two places that read environment variables: your API gateway and your Developer Portal. Both use the variables you set in the editor, but each one gets a different set of variables at a different time.

API gatewayDeveloper Portal
Variables availableAll variables, including secretsOnly configuration variables whose names start with ZUPLO_PUBLIC_ or ZUDOKU_PUBLIC_
When they're readAt runtimeWhen the portal is built
Who can see valuesOnly your gateway codeAnyone who visits the portal, because values are embedded in the published site
How to read themenvironment.VAR_NAME in code, $env(VAR_NAME) in config filesprocess.env.VAR_NAME in zudoku.config.tsx, import.meta.env.VAR_NAME in components
Variables Zuplo setsZUPLO_ENVIRONMENT_STAGE, ZUPLO_ENVIRONMENT_NAME, and othersZUPLO_ENVIRONMENT_TYPE, ZUPLO_SERVER_URL, and ZUPLO_BUILD_ID
ReferenceGateway environment variablesDev Portal environment variables

Your gateway can also read ZUPLO_PUBLIC_ and ZUDOKU_PUBLIC_ variables. Never put a secret in a variable with one of these prefixes. Zuplo doesn't send secret variables to the Developer Portal build, even if their names have a public prefix.

Same name, different values

ZUPLO_ENVIRONMENT_TYPE means different things in the gateway and in the Developer Portal build. To check whether the code is running in production, use ZUPLO_ENVIRONMENT_STAGE in your gateway (production) and ZUPLO_ENVIRONMENT_TYPE in your Developer Portal (PRODUCTION).

Environment Variable Editor

To set environment variables in your project, click Settings and then select Environment Variables.

To create a new variable, click Add variable.

Adding a new environment variable

Enter the name and value of your environment variable and select if you would like the value to be a secret or a regular value. Values take effect on the next deployment of each environment.

Environments

Environment variables can be applied to one or many different environments. You can select one or more environments in which to apply the variable.

EnvironmentDescription
ProdThe environment that's deployed from your default branch in source control. This is usually called main.
PreviewAny environment that's deployed from source control that's not the default branch. (for example staging or preview). This also includes any branch that's created from a pull request.
Development (Working Copy)Any environment that's deployed while developing with the portal. Each developer gets their own development environment. These environments are always deployed to zuplo.dev

For the Preview environment option, a specific named environment can be selected. For example, if you want a variable set only for the environment deployed from the staging branch in source control.

For the Working Copy option, developers can set a personal override. This value ONLY applies to the developer who set the value.

A single environment variable name can't overlap environments. For example, if you set a variable named MY_VAR and select all the environments a second variable named MY_VAR can't be set on say the Production environments.

Manage variables from the CLI or API

You can create, update, and delete variables without opening the Zuplo Portal. This is useful in CI/CD pipelines and scripts. The CLI commands call the Zuplo Developer API, so you can also call the Variables endpoints directly.

ActionCLI commandDeveloper API
Createzuplo variable createPOST .../branches/{branchName}/variables
Updatezuplo variable updatePATCH .../variables/{variableName}
Deletezuplo variable deleteDELETE .../variables/{variableName}
TerminalCode
zuplo variable create --name BASE_URL --value https://api.example.com \ --is-secret false --branch main zuplo variable delete --name BASE_URL --branch main

See the Variables operations in the Zuplo Developer API reference for the request and response formats.

Which variable the branch selects

Every variable command takes a branch. The branch picks which variable the command works on:

  • On your project's default branch (usually main), the command works on the variable that targets Production.
  • On any other branch, the command works on the variable scoped to that Preview branch.

Deleting a variable removes the whole variable from every environment it targets, not only from the branch you passed. For example, a variable that applies to Production and to a Preview branch is gone from both after you delete it from either.

After you change a variable

As with the editor, a change only reaches an environment on its next deployment. Redeploy the environment for a deletion, update, or new variable to take effect.

When delete returns 404

Delete returns 404 when the branch doesn't select an existing variable:

  • No variable with that name exists for the branch.
  • The variable is a Preview variable that applies to all branches. No branch selects it, so you can't delete it from the CLI or API. Manage it in the editor instead.
  • The project has no default branch and you're deleting a Production variable. Without a default branch, only branch-scoped variables can be selected.

Reserved Environment Variables

Names that start with ZUPLO_, __ZUPLO, or ZUDOKU_ are reserved for Zuplo, with these exceptions:

  • ZUPLO_PUBLIC_ and ZUDOKU_PUBLIC_ are allowed. Use them for values your Developer Portal needs.
  • A few Zuplo settings, such as ZUPLO_LOG_LEVEL, are allowed.

Use only letters, digits, and underscores in variable names.

Local Development

Local development doesn't use the variables you set in the Zuplo Portal. Your local gateway reads variables from a .env file in your project, and your local Developer Portal reads them from a .env file in its own folder. See Configuring Environment Variables Locally.

Next Steps

Last modified on