Skip to main content

Deployments · Secret managers · Doppler

Doppler

Connect one Doppler config with a read-only service token. Your services read its secrets on every deploy, and Doppler stays the place you change them.

How secret managers work, where they can be used and how a secret reads from one are the same for every secret manager: see Secret managers. This page covers what's specific to Doppler.

You connectSign-inA secret's key is
One Doppler project and configA service token for that configThe secret's name in that config, for example DATABASE_URL

Before you start​

  • A Doppler project and config that hold the secrets, for example the prd config of your api project.
  • Owner or admin in your ComputeSphere account. Owners and admins connect secret managers; every project member can then use them.
  • A service token for that config. In Doppler, open the config, then Access → Service Tokens → Generate, and choose Read access. A service token reads one config only, which is exactly what a secret manager needs: it can't see your other configs or your workplace. Use a service token rather than a personal or service account token, which can read far more than the one config.

One secret manager reads one config. To read from two configs (say stg and prd), connect each as its own secret manager, and choose for each one the environments that can use it.

Connect​

  1. In the console, open Settings → Secret managers and click Connect a secret manager.
  2. Fill in:
    • Name: lowercase letters, numbers and dashes, for example app-doppler. Secrets and .env links refer to the secret manager by this name.
    • Type: Doppler.
    • Project and Config: the Doppler project and config the token was made for.
    • Service token: stored encrypted. ComputeSphere never shows it again.
    • Where it can be used: all projects, or the projects (and their environments) you pick.
  3. Click Connect. ComputeSphere signs in with the token and checks the config before anything is saved.

To replace the token, generate a new one in Doppler, edit the secret manager and enter it. Leaving the field empty keeps the stored token. The new token is tested before it's saved, and reads use it from then on. Then revoke the old token in Doppler.

Use a secret​

Add a secret from a secret manager on a service or an environment, as described in Use a secret from a secret manager. For Doppler:

  • The key is the secret's name in the config. It defaults to the name you give the secret in your service, so a service secret DATABASE_URL reads Doppler's DATABASE_URL unless you enter another key.
  • In a .env import, DATABASE_URL=ref://app-doppler reads DATABASE_URL, and STRIPE_KEY=ref://app-doppler/STRIPE_LIVE_KEY reads STRIPE_LIVE_KEY as STRIPE_KEY. See Import a .env with links.
  • Doppler's own DOPPLER_ variables (DOPPLER_PROJECT, DOPPLER_CONFIG, DOPPLER_ENVIRONMENT) set up the Doppler CLI, not your app. Link all in a .env import leaves them out.
  • Each deploy reads the latest value in the config. A change in Doppler reaches the service on its next deploy or restart.

Troubleshooting​

In each message, app-doppler stands for your secret manager's name and DATABASE_URL for a secret's key.

When you connect, or click Test. The test signs in and checks the project and config:

MessageWhat it meansWhat to do
Couldn't sign in to app-doppler. Check the credential, then test again.Doppler didn't accept the service token: it was revoked, expired or mistyped.Generate a new service token for the config and enter it.
app-doppler refused access. Check what the credential is allowed to read.The token signed in but can't read this config.Make the token for the same project and config you entered.
app-doppler couldn't find what these settings point to. Check the settings, then test again.The project or config doesn't exist in Doppler.Check the spelling of the project and the config.
app-doppler is limiting requests. Try again in a few minutes.Doppler is rate-limiting the token.Wait, then test again.
app-doppler didn't answer. Try again in a few minutes.Doppler didn't respond in time.Wait, then test again.

When a deploy reads a secret. A deploy's error and the secret's Can't read state name the secret:

MessageWhat it meansWhat to do
DATABASE_URL isn't in app-doppler at the source's root.The config has no secret with that name.Add it in Doppler, or correct the secret's key.
app-doppler refused access to DATABASE_URL.The token can no longer read the config.Give the secret manager a token for that config.
Couldn't sign in to app-doppler. Check the credential, then test again.The token was revoked or expired.Generate a new service token and enter it.
This environment can't use app-doppler. Allow it in the source's settings.The secret manager isn't allowed in this project or environment.Add it under Where it can be used.
DATABASE_URL in app-doppler is larger than 64 KB.The value is over the size limit for one secret.Store a smaller value, or split it.

These answers stop the deploy before anything changes. When Doppler is rate-limiting or doesn't answer, the deploy goes ahead with the last value read and the secret shows Using last value.

For how a definite answer and no answer affect a deploy, see When the secret manager doesn't answer, or says no.

Current limits​

  • One config per secret manager. Connect a second secret manager for a second config.
  • No live sync between deploys. A change in Doppler reaches the service on its next deploy or restart.

Next​