3 min read

Doppler Encrypted Secrets Snapshots for High Availability

Ensuring applications can always access their secrets.

Nov 10, 2022
Ryan Blunden Avatar
Ryan Blunden
Senior Developer Advocate
Doppler Encrypted Secrets Snapshots for High Availability
Back to the blog
Doppler Encrypted Secrets Snapshots for High Availability

Ideally, fetching secrets at runtime by your application is avoided altogether using Doppler integrations (e.g. Doppler Kubernetes Secrets Operator), which continuously sync secrets to your hosting environment ahead of time, but this won't always be possible.

For legacy applications, on-prem, and virtualized environments where secrets must be fetched at runtime, bundling Doppler CLI secrets snapshots into your application provides a robust failsafe in the event Doppler's API is unreachable.

The result is similar to a GitOps secrets approach, but without the messy business of committing encrypted secrets to Git repositories can be avoided.

Build. Encrypt. Deploy. Fallback.

Doppler secrets snapshots are bundled into the application build during CI/CD with a single command:

1doppler secrets download secrets.json.enc

Then to fallback to a secrets snapshot when running your application:

1doppler run --fallback secrets.json.enc -- ./app-start.sh

Secrets snapshots aren't just for high availability. They're perfect for network-restricted environments and offer protection if Doppler's API rate limit is exceeded.

The addition of the --fallback-only instructs the CLI to only use the snapshot:

1doppler run \
2 --fallback secrets.json.enc \
3 --fallback-only -- ./app-start.sh

Now let's look into passphrase usage for encrypting and decrypting secrets snapshots.


By default, the CLI configuration is used to construct the passphrase, which is typically the Service Token value exposed via the DOPPLER_TOKEN environment variable. While this is the simplest solution, setting the passphrase explicitly has the benefits of:

* Only using the DOPPLER_TOKEN for authentication

* Allowing the passphrase and DOPPLER_TOKEN values to be rotated independently

Most importantly, your implementation must guarantee the passphrase remains constant from build to deployment during a release. As these are infrastructure secrets, we recommend a dedicated infra project for each application containing only the DOPPLER_TOKEN and (should you use a passphrase) a DOPPLER_PASSPHRASE.

‎Doppler integrations then keep infrastructure secrets in sync between your build and your deployment environments, eliminating the risks associated with manual copying and pasting.

The following video demonstrates how to set up an infra project in three simple steps:

With the required pieces in place, let's move on to creating and using secrets snapshots.


With the DOPPLER_TOKEN and DOPPLER_PASSPHRASE injected into your build environment (e.g. GitHub Action Secrets), we can now create the secrets snapshot file:

1doppler secrets download \
2  --passphrase "$DOPPLER_PASSPHRASE" \
3  secrets.json.enc

Secrets snapshots also support name transformers and download formats:

1# ASP.NET Core secrets snapshot
2doppler secrets download \
3 --passphrase "$DOPPLER_PASSPHRASE" \
4 --format dotnet-json \
5 appsettings.json.enc

Ensure the secrets snapshot file is included in your build, then you're done!


With the DOPPLER_TOKEN and DOPPLER_PASSPHRASE injected into the deployment environment via automation (e.g Ansible), the Doppler CLI will attempt to fetch the latest version of secrets using the secrets snapshot as a fallback:

1doppler run \
2  --passphrase "$DOPPLER_PASSPHRASE" \
3  --fallback secrets.json.enc -- ./start-app.sh


Doppler secret snapshots are your high-availability solution to ensure applications can always access their secrets.

Using Docker? Check out our dedicated Docker High Availability documentation to learn more.

Stay up to date with new platform releases and get to know the team of experts behind them.

Related Content

Explore More