Aller au contenu
1337skills 1337skills - Aide-mémoires

Doppler Cheat Sheet

Overview

Doppler is a universal secrets management platform that centralizes application configuration and secrets across all environments, projects, and teams. It replaces scattered .env files, hardcoded credentials, and fragmented secret stores with a single source of truth that integrates with your development workflow, CI/CD pipelines, and cloud infrastructure.

Doppler provides a CLI for local development, native integrations with platforms like AWS, GCP, Azure, Vercel, Netlify, GitHub Actions, and Docker, and supports secret rotation, versioning, audit logs, and role-based access control. It offers a branching model for configs with environments (development, staging, production) and personal overrides for individual developers.

Installation

# macOS
brew install dopplerhq/cli/doppler

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -sLf --retry 3 --tlsv1.2 --proto "=https" \
  'https://packages.doppler.com/public/cli/gpg.DE2A7741A397C129.key' | \
  sudo gpg --dearmor -o /usr/share/keyrings/doppler-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/doppler-archive-keyring.gpg] https://packages.doppler.com/public/cli/deb/debian any-version main" | \
  sudo tee /etc/apt/sources.list.d/doppler-cli.list
sudo apt-get update && sudo apt-get install doppler

# Alpine
apk add doppler

# Docker
docker pull dopplerhq/cli

# npm (for CI environments)
npm install -g @dopplerhq/cli

# Verify
doppler --version

Authentication

# Interactive login (opens browser)
doppler login

# Service token (for CI/CD and servers)
export DOPPLER_TOKEN="dp.st.production.xxxx"

# Personal token from environment
export DOPPLER_TOKEN="dp.pt.xxxx"

# Check auth status
doppler whoami

# Logout
doppler logout

Project Setup

# Initialize project in current directory
doppler setup

# Select project and config interactively
doppler setup --project my-api --config dev

# Check current configuration
doppler setup --check

# List all projects
doppler projects

# Create a new project
doppler projects create my-new-project

# List environments/configs
doppler configs --project my-api

Secrets Management

# List all secrets
doppler secrets

# Get all secrets as JSON
doppler secrets --json

# Get a specific secret
doppler secrets get DATABASE_URL

# Get secret value only (no name)
doppler secrets get DATABASE_URL --plain

# Set a secret
doppler secrets set API_KEY "sk-abc123..."

# Set multiple secrets
doppler secrets set DB_HOST="db.example.com" DB_PORT="5432" DB_NAME="myapp"

# Set from file
doppler secrets set API_CERT --file ./cert.pem

# Delete a secret
doppler secrets delete OLD_SECRET

# Download secrets as .env
doppler secrets download --no-file --format env > .env

# Download as JSON
doppler secrets download --no-file --format json > secrets.json

Running Commands with Secrets

# Inject secrets into a command
doppler run -- node server.js

# Inject into docker
doppler run -- docker compose up

# Inject into any command
doppler run -- ./deploy.sh

# Fallback to .env file if Doppler is unavailable
doppler run --fallback .env.backup -- node server.js

# Save fallback file
doppler secrets download --fallback --no-file --format env > .env.backup

# Specific project and config
doppler run --project my-api --config production -- node server.js

# Mount secrets as a file
doppler run --mount secrets.json --mount-format json -- node server.js

Config Branching

# List configs for a project
doppler configs --project my-api

# Create a branch config (personal override)
doppler configs create dev_john --project my-api --environment dev

# Clone a config to a new environment
doppler configs clone --project my-api --config staging --name staging_v2

# Lock a config (prevent changes)
doppler configs lock --project my-api --config production

# Unlock
doppler configs unlock --project my-api --config production

# Delete a config
doppler configs delete --project my-api --config dev_john

Integrations

Docker

# Using service token
docker run -e DOPPLER_TOKEN="dp.st.production.xxxx" \
  dopplerhq/cli run -- your-command

# Docker Compose
# docker-compose.yml
# services:
#   app:
#     image: my-app
#     environment:
#       - DOPPLER_TOKEN=${DOPPLER_TOKEN}
#     entrypoint: ["doppler", "run", "--"]
#     command: ["node", "server.js"]

GitHub Actions

name: Deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dopplerhq/cli-action@v3
      - run: doppler run -- ./deploy.sh
        env:
          DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN }}

Kubernetes

# Create Kubernetes secret from Doppler
doppler secrets download --no-file --format json | \
  kubectl create secret generic my-app-secrets --from-file=secrets.json=/dev/stdin

# Using Doppler Kubernetes Operator
# Install the operator
helm repo add doppler https://helm.doppler.com
helm install doppler-operator doppler/doppler-operator

# Create DopplerSecret resource
# apiVersion: secrets.doppler.com/v1alpha1
# kind: DopplerSecret
# metadata:
#   name: my-app-secrets
# spec:
#   tokenSecret:
#     name: doppler-token
#   managedSecret:
#     name: my-app-env
#     type: Opaque

Vercel

# Sync secrets to Vercel (via Doppler dashboard integration)
# Or manually
doppler secrets download --no-file --format env | \
  while IFS='=' read -r key value; do
    vercel env add "$key" production <<< "$value"
  done

Service Tokens

# Create a service token
doppler configs tokens create \
  --project my-api \
  --config production \
  --name "CI/CD Token" \
  --max-age 90d

# List service tokens
doppler configs tokens --project my-api --config production

# Revoke a service token
doppler configs tokens revoke --project my-api --config production --slug TOKEN_SLUG

Advanced Usage

Secret Referencing

# Reference secrets across configs
# In Doppler dashboard, set a secret value to:
# ${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME}
# Doppler will resolve the references

Audit Logs

# View activity logs
doppler activity-logs --project my-api

# Filter by config
doppler activity-logs --project my-api --config production

Secrets Rotation

# Update a secret (creates new version)
doppler secrets set API_KEY "new-rotated-key"

# View secret history
doppler activity-logs --project my-api --config production

# Rollback config to a specific version
doppler configs rollback --project my-api --config production --version 3

Import Existing Secrets

# Import from .env file
doppler secrets upload .env --project my-api --config dev

# Import from JSON
doppler secrets upload secrets.json --project my-api --config dev

Configuration

# Global config location: ~/.doppler/.doppler.yaml

# Project-level config (.doppler.yaml in project root)
# setup:
#   project: my-api
#   config: dev

# Environment variables
export DOPPLER_TOKEN="dp.st.xxxx"           # Service token
export DOPPLER_PROJECT="my-api"             # Default project
export DOPPLER_CONFIG="production"          # Default config
export DOPPLER_API_HOST="https://api.doppler.com"  # Custom API host

Troubleshooting

IssueSolution
not authenticatedRun doppler login or set DOPPLER_TOKEN
Wrong project/configRun doppler setup to reconfigure; check .doppler.yaml
Secret not foundVerify secret name with doppler secrets; check config
Service token expiredCreate a new token; check --max-age setting
doppler run hangsCheck network connectivity to api.doppler.com
Fallback file staleRegenerate with doppler secrets download --fallback
Docker can’t access secretsEnsure DOPPLER_TOKEN is passed as environment variable
Import failsCheck file format (JSON or dotenv); verify project/config exists