Configuring Environment Variables
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 gateway | Developer Portal | |
|---|---|---|
| Variables available | All variables, including secrets | Only configuration variables whose names start with ZUPLO_PUBLIC_ or ZUDOKU_PUBLIC_ |
| When they're read | At runtime | When the portal is built |
| Who can see values | Only your gateway code | Anyone who visits the portal, because values are embedded in the published site |
| How to read them | environment.VAR_NAME in code, $env(VAR_NAME) in config files | process.env.VAR_NAME in zudoku.config.tsx, import.meta.env.VAR_NAME in components |
| Variables Zuplo sets | ZUPLO_ENVIRONMENT_STAGE, ZUPLO_ENVIRONMENT_NAME, and others | ZUPLO_ENVIRONMENT_TYPE, ZUPLO_SERVER_URL, and ZUPLO_BUILD_ID |
| Reference | Gateway environment variables | Dev 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.
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.
| Environment | Description |
|---|---|
| Prod | The environment that's deployed from your default branch in source control. This is usually called main. |
| Preview | Any 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.
Reserved Environment Variables
Names that start with ZUPLO_, __ZUPLO, or ZUDOKU_ are reserved for Zuplo,
with these exceptions:
ZUPLO_PUBLIC_andZUDOKU_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
- Gateway environment variables: read variables in code, policies, route handlers, and URL rewrites, and the variables Zuplo sets for your gateway.
- Dev Portal environment variables:
read variables in
zudoku.config.tsxand components, and the variables Zuplo sets when it builds your portal.