Accessing Secrets
reading time 3 minutes
The Doppler CLI is supremely flexible when it comes to accessing your secrets and in this guide, we'll show you the most common usage patterns:
Injection
Whether developing locally or in prod, your can run your app via the doppler run command which injects secrets as environment variables directly into the process:
doppler run -- npm start
If your application needs to access secrets using a file, see the Mounting section below.
Mounting
For applications that read secrets from a file, you can mount an ephemeral .env, JSON, or a custom file format using a secrets template .
Your secrets are mounted as a Linux named pipe that can be read like a file and is automatically cleaned up when the Doppler process exits, making it the only secure method for supplying secrets via the file system.
Simply specify the --mount
flag and pass the name of the file to mount. The format will automatically be detected for .env and .json files.
To mount an .env file:
doppler run --mount .env -- npm start
doppler run --mount .env -- php artisan serve
To mount a JSON file:
doppler run --mount env.json -- npm start
Specify the format using --mount-format
if the extension doesn't map to a known format:
doppler run --mount app.config --mount-format json -- npm start
You can also use a custom template. For example, lets configure Firebase's Cloud Functions emulator using a .runtimeconfig.json
file:
# 1. Create the template
echo '{ "doppler": {{tojson .}} }' > .runtimeconfig.tmpl
# 2. Mount the .runtimeconfig.json and run the emulator
doppler run \
--mount .runtimeconfig.json \
--mount-template .runtimeconfig.tmpl -- \
firebase emulators:start --only functions
To further increase security, you can restrict the number reads using the --mount-max-reads
flag. For example, PHP configuration caching that only needs to read the .env file once:
doppler run --mount .env --mount-max-reads 1 \
--command="php artisan config:cache && php artisan serve"
Get Values
Fetch the plain value of a single secret, e.g. JSON credentials used by a CLI:
doppler secrets get GCP_SERVICE_ACCOUNT_JSON --plain > gcp_credentials.json
You can also use a secret value in a shell command by using the --command
flag, e.g. performing a curl
request using Basic Authentication:
doppler run --command='curl -u $USER:$TOKEN https://example.com'
You can download secrets to a file when environment variables aren't sufficient, e.g. supplying a TLS certificate and key to a webserver:
doppler secrets get TLS_CERT --plain > /etc/tls/cert.pem
doppler secrets get TLS_KEY --plain > /etc/tls/key.pem
Get the values of multiple secrets at once in either plain or JSON format:
# Plain
doppler secrets get DOPPLER_PROJECT DOPPLER_CONFIG --plain
# JSON
doppler secrets get DOPPLER_PROJECT DOPPLER_CONFIG --json
You can also get a nice dashboard-style view with the option to exclude the values:
# Names and values
doppler secrets
# Just names
doppler secrets --only-names
# Names as a JSON array
doppler secrets --only-names --json | jq keys
Filtering
You can use the doppler secrets download
command in conjunction with tools such as grep
and jq
to get a filtered list of secrets.
Filter secrets in env format using grep:
# Get secrets containing the string "CLOUDWATCH"
doppler secrets download --no-file --format env | grep CLOUDWATCH
# Get secrets starting with "CLOUDWATCH"
doppler secrets download --no-file --format env | grep ^CLOUDWATCH
Filter objects in JSON format using jq
:
# Get secrets containing the string "CLOUDWATCH"
doppler secrets download --no-file --format json | \
jq -r '. | to_entries[] | select(.key | contains("CLOUDWATCH)")) | { (.key): (.value)}' | \
jq -s add
# Get secrets starting with "CLOUDWATCH"
doppler secrets download --no-file --format json | \
jq -r '. | to_entries[] | select(.key | startswith("CLOUDWATCH")) | { (.key): (.value)}' | \
jq -s add
You can also combine filtering with formatting. For example, create an SSH authorized_keys
file with the value from secrets with an SSH_PUB_KEY_
prefix.
# If secrets in Doppler were
# SSH_PUB_KEY_SERVER_A="ssh-ed25519 AAA..."
# SSH_PUB_KEY_SERVER_B="ssh-ed25519 BBB..."
doppler secrets download --no-file --format env-no-quotes | grep ^SSH_PUB_KEY_ | cut -d"=" -f2 > authorized_keys && chmod 600 authorized_keys
Downloading
Whenever you can avoid downloading secrets in an unencrypted form to the file system, and if so, remove it as soon as possible, e.g. once your application or script exits.
Using the dopper secrets download
command, you can download all in a variety of formats:
- json (default)
- yaml
- env
- env-no-quotes
- docker
For example, to download secrets as a .env
file:
# Avoid storing secrets unencrypted whenever possible
doppler secrets download --no-file --format env > .env
Thanks to the magic that is bash process substitution (meaning this won't work for shell scripts executed with sh
), we can use the Doppler CLI to supply secrets to a command expecting a file, but without having to save it locally. Best of both worlds!
Works great with Docker:
docker run \
--env-file <(doppler secrets download --no-file --format docker) \
your/image
And Kubernetes:
kubectl create secret generic \
doppler-env-vars --from-env-file <(doppler secrets download --no-file --format docker)
You can even embed the secrets as part of a larger output, such as syncing Doppler secrets to AWS Lambda using JSON:
aws lambda update-function-configuration \
--function-name doppler-test \
--environment $(echo "{\"Variables\":$(doppler secrets download --no-file)}")
You even transform the syntax of secret keys and values using jq
when you need a specific format, such as Apache environment variable declarations for a PHP application:
doppler secrets download --no-file | jq -r '. | to_entries[] | "SetEnv \(.key) \"\(.value)\""' > apache/env-vars.conf
That should give you a few ideas for how you can work with Doppler secrets outside of the doppler run
command.
Let us know if we've missed anything and we'd be glad to add your tip to the list!
FAQs
How do I export Doppler secrets into the current shell?
A situation may arise when you need to populate a shell with environment variables from Doppler.
Exercise caution with this functionality as every process executed in your shell will now have access to your secrets.
You could create a child shell spawned by the Doppler CLI:
doppler run -- sh -c 'bash'
doppler run -- sh -c 'zsh'
doppler run -- sh -c 'sh'
Or use doppler secrets download
in conjunction with process substitution to promote Doppler local variables to environment variables.
set -a
source <(doppler secrets download --no-file --format env)
set +a
Updated 20 days ago