This guide is designed to get you completely set up with Doppler when using Docker. We will cover everything from constructing your docker images, high availability, building your images with the Doppler credentials, and debugging locally.
When constructing your Dockerfile, you can use the official Doppler base image. The base images come in a couple of flavors depending on what other dependencies you have. You can also use a different base image.
Alpine base image (
Node 12 image (
Python 3 image (
Ruby 2 image (
The Doppler CLI follows semantic versioning. All images have tags for their major, minor, and patch versions. We recommend locking to a major version to prevent breaking changes.
Updates you'll receive
Patch (not recommended)
Now let's put all this together with a sample Dockerfile. This Dockerfile will:
- Either use the Doppler image or a custom one
- Instruct Docker to expect 3 Doppler credentials as build arguments.
- Configure the Doppler CLI to use those credentials.
- Cache secrets at build time, which will later be used for high availability.
- Fetch your latest secrets and then run your command with the secrets injected as environment variables.
# Doppler base image FROM dopplerhq/cli:3 # Pass in Doppler credentials at build time ARG DOPPLER_TOKEN ARG DOPPLER_PROJECT ARG DOPPLER_CONFIG # Configure the CLI to use the Doppler credentials RUN doppler setup --no-prompt --silent # Cache secrets to an encrypted file at build time for high availability. RUN doppler run -- echo "Saving a fallback file" # Fetch the latests secrets. If the CLI fails to connect # with Doppler the CLI will fallback to the cached secrets file. # The CLI will then inject those secrets as environment variables. ENTRYPOINT doppler run -- ./your-comand-here
# Some other base image FROM alpine # Pass in Doppler credentials at build time ARG DOPPLER_TOKEN ARG ENCLAVE_PROJECT ARG ENCLAVE_CONFIG # Install the Doppler CLI RUN (curl -Ls https://cli.doppler.com/install.sh || wget -qO- https://cli.doppler.com/install.sh) | sh # Configure the CLI to use the Doppler credentials RUN doppler enclave setup --no-prompt --silent # Cache secrets to an encrypted file at build time for high availability. RUN doppler run -- echo "Saving a fallback file" # Fetch the latests secrets from Enclave. If the CLI fails to connect # with Doppler the CLI will fallback to the cached secrets file. # The CLI will then inject those secrets as environment variables. ENTRYPOINT doppler run -- ./entrypoint.sh
For security reasons, you may want to change the user in your image. When doing so, please make sure you change the user before you run the
doppler setup command as the CLI uses the user's home directory when storing the Doppler configuration file.
# Change docker user to "node" USER node # Configure the CLI to use the Doppler credentials RUN doppler setup --no-prompt --silent
When building your Docker image you must supply 1 build argument. This argument is a token that authorizes the CLI to fetch secrets. Since in most cases a service token will be used, the project and config credentials do not need to be provided, as a service token can only access one config. If you do not have a service token, here is a quick guide to show you how to create one.
In this example, we are going to add the tag
doppler-test to the image so we can use it in the Running the Image step.
docker build . \ -t doppler-test \ --build-arg "DOPPLER_TOKEN=$DOPPLER_TOKEN"
While you are developing, you can use your local configuration when building the image. In this case, we are providing the project and config credentials as well, since a service token is not being used.
docker build . \ -t doppler-test \ --build-arg "DOPPLER_TOKEN=$(doppler configure get token --plain)" \ --build-arg "DOPPLER_PROJECT=$(doppler configure get project --plain)" \ --build-arg "DOPPLER_CONFIG=$(doppler configure get config --plain)"
Now let's run the newly built
docker run --rm -it doppler-test
If your application needs to expose a port, you can use the Docker
-p flag. For this example, we will use port
3030 to expose your web application.
docker run --rm -it -p 3030:3030 doppler-test
Running one-off Doppler commands in Docker is simple. The main thing to remember is you are switching the
doppler command for a
docker run command.
Let's take a look at a quick example. For this example, we are going to use the Doppler alpine image to fetch secrets. Let's first run a simple command like checking the current version of the Doppler CLI.
docker run --rm -it dopplerhq/cli:3 --version
Now that we have tested a simple command, let's try something a little more complex like fetching your secrets in JSON format.
docker run --rm -it dopplerhq/cli:3 secrets --token $DOPPLER_TOKEN --json
Now that you have local development running, let’s set up authentication for staging and production with Service Tokens.
Updated 2 days ago