Environment variables and secrets
Configure services at three scopes, keep secrets encrypted, and reference them by name.
Variables and secrets are set on a project, an environment or a service. A service receives the merge of all three when it is deployed.
Scopes and precedence
When the same key is set at more than one scope, the most specific one wins:
service > environment > projectFor example, with LOG_LEVEL=info on the project, LOG_LEVEL=warn on the production
environment and LOG_LEVEL=debug on one service, that service gets debug and every other
service in production gets warn. The service's Effective variables view shows each key's
final value and the scope it comes from.
Variables
- Keys use uppercase letters, digits and
_, do not start with a digit, and are at most 128 characters. A key is unique within its scope (ENV_KEY_DUPLICATE). - A value is a single line of at most 32 KiB. A line break or NUL byte is rejected with
ENV_VALUE_MULTILINE: encode multi-line values, such as certificates or keys, as base64 and decode them in the application. - A scope holds at most 200 variables (
ENV_LIMIT_REACHED).
Secrets
A secret is a named value encrypted at rest with the master key. After it is saved, its value is never shown again, in the panel, the API, logs or activity. It can only be replaced or deleted.
- Names use lowercase letters, digits and
_, start with a letter, and are at most 64 characters. A name is unique within its scope (SECRET_NAME_DUPLICATE). - Values are single-line, like variables.
- A scope holds at most 100 secrets (
SECRET_LIMIT_REACHED).
Referencing a secret
A variable uses a secret by naming it, never by copying its value:
| Key | Value |
|---|---|
DATABASE_URL | <secret:database_url> |
The reference resolves with the same precedence as variables: a secret on the service wins over
one with the same name on the environment, which wins over the project. A reference to a secret
that exists in no visible scope is rejected with SECRET_NOT_FOUND. A secret that variables
still reference cannot be deleted (SECRET_IN_USE); the error lists them.
Changes apply on the next deploy
Editing a variable or replacing a secret does not touch the running container. The service shows Redeploy to apply. until you deploy again. Each deploy records which secret version it used.
Exposure on the server
At deploy time the values are decrypted and written to a mode 0600 file in the deployment
workspace, passed to docker create --env-file, and the file is removed at once. The container
then holds them like any environment variable: anyone with Docker access on that server can read
them with docker inspect. Restrict Docker access on the server accordingly.
Rotation
To rotate an application secret, replace its value, then redeploy every service that uses it. Until the redeploy, running containers keep the old value.
The master key that encrypts secrets is rotated with secrets rotate, which re-encrypts every
stored credential and secret; see Troubleshooting.