Environment variables and secrets

Every detail of project env vars: scopes, secrets, shared env vars, CI vars and the CLI commands.

Each project has its own env vars, set separately for production and preview deployments. An org can also share vars with several projects, and CI runs have vars of their own.

• Build vars are passed to the Gradle build.
• Runtime vars are passed to your running Ktor apps.

A var is both by default. Changes apply on the next deployment; to apply them right away, redeploy the latest production deployment (the Redeploy production button in the panel’s Env tab).

Keys use letters, digits and _ and don’t start with a digit. PORT and names starting with ATOLL_ are reserved. Values can be up to 64 KB, and a project can have up to 500 vars across both environments.

​

Secrets

Mark API keys, passwords and tokens as secret. A secret’s value can’t be read back from the panel, the CLI or the API, and it is masked as **** in deployment logs (values of 4 or more characters; shorter ones are not masked). To change a secret, set a new value. Anyone who can read a project sees its plain vars; setting and removing vars needs the developer role.

The org’s Environment Variables page in the panel lists the vars of every project of the org in one place, with filters, and has tabs for shared vars and CI vars.

​

Shared env vars

A shared var belongs to the org and is passed to the projects it is linked to: some of them, or all projects, which includes projects created later. Use them for values many projects need, such as an error tracker DSN or an internal API URL.

Each shared var applies to a set of targets: production and preview deployments, and ci for CI runs. All three by default. A key can have one value per target, so SENTRY_DSN can have one value for production and another for preview and CI. Shared vars have the same rules and flags as project vars: secret, build and runtime (build and runtime only matter for deployments). An org can have up to 500.

When the same key comes from several places, the most specific one wins:

1. the project’s own var,
2. a shared var linked to the project,
3. a var from a connected data store.

The project’s Env tab shows the shared vars linked to it, marked overridden where a project var with the same key wins.

Org admins and owners create, edit, link and delete shared vars. Every org member sees them, but never the values of secret ones.

​

CI vars

CI vars are a project’s vars for CI runs only; deployments never get them. They are plain or secret, and secrets are masked in CI logs like in deployment logs. Runs get the project’s CI vars and the shared vars with the ci target, not the project’s deployment vars. Setting and removing CI vars needs the developer role.

​

CLI

The project defaults to the name of the current directory, like atoll deploy; pass --project to choose another. --env defaults to production.

atoll env ls [--env preview]                        # list vars; secrets show as (secret)
atoll env set API_URL=https://api.example.com       # set a var
atoll env set STRIPE_KEY=sk_live_... --secret       # set a secret
atoll env set GRADLE_OPTS=-Xmx4g --no-runtime       # build only
atoll env set SENTRY_DSN=... --no-build --env preview
atoll env rm API_URL                                # remove a var
atoll env import .env.production [--secret]         # set every var of a .env file

--shared works on the org’s shared vars instead. The org defaults to the one picked with atoll orgs switch, else your personal org; pass --org to choose another. --target takes production, preview and ci, comma-separated.

atoll env ls --shared [--target ci]                                  # key, targets, value and linked projects
atoll env set --shared SENTRY_DSN=https://... --all-projects         # every project, all targets
atoll env set --shared API_URL=https://... --link shop,admin         # some projects
atoll env set --shared API_URL=https://staging... --target preview,ci
atoll env rm --shared API_URL [--target ci]                          # remove it, or only from some targets
atoll env import --shared .env.shared --secret --all-projects

Setting a shared key that already exists updates it. It keeps its targets unless you pass --target, and its links unless you pass --link or --all-projects (--link "" unlinks it from every project). Setting a key for only some of its targets gives those targets their own value; the old value stays for the rest.

--ci works on the project’s CI vars. --env, --no-build and --no-runtime don’t apply to them.

atoll env ls --ci
atoll env set --ci SONAR_TOKEN=... --secret
atoll env rm --ci SONAR_TOKEN
atoll env import --ci .env.ci

Values typed on the command line can end up in your shell history. For secrets, prefer atoll env import with a file you delete afterwards, or the panel.

.env files contain KEY=value lines. export prefixes, blank lines and # comments are ignored. Values can be quoted: single quotes keep the text as is, and double quotes understand \n, \" and \\. Both kinds of quoted values may span several lines.

​

Self-hosting: encryption keys

With a database, the server encrypts every value (project, shared and CI vars) with AES-256-GCM before storing it. It reads the keys from ATOLL_ENV_KEYS and won’t start without them:

ATOLL_ENV_KEYS=k1:$(openssl rand -base64 32)

The setting is a comma-separated list of id:base64key entries. New values are encrypted with the first key; the other keys are only used to read older values. To rotate keys:

1. Add a new key at the end of the list on every server, e.g. k1:<old>,k2:<new>, and restart.
2. Move it to the front, k2:<new>,k1:<old>, and restart. On start, the server encrypts the values stored under older keys again with the first key.
3. Once every server runs with the new order, restart them once more. During the rolling restart in step 2, servers still on the old order may have written values with the old key; this restart re-encrypts those too. To check, SELECT count(*) FROM env_vars WHERE key_id = 'k1' must return 0.
4. Remove the old key: k2:<new>.

Keep the keys safe and back them up together with the database. Values can’t be recovered without their key. The server refuses to start if a stored value needs a key that is missing from ATOLL_ENV_KEYS, or if a key under a known id doesn’t match.

Without a database, env vars are kept in memory, unencrypted, and lost on restart.