Documentation

We are here to help you get from zero to one fast.

Get Started    Discussions

Docker

reading time 5 mins

This guide will show you three production-ready ways of using Doppler to supply app config and secrets to your Docker containers:

Option

Usecase

Dockerfile

For users who want to install the Doppler CLI in their Dockerfile.

Container Env Vars

For users who want to inject the secrets from Doppler on docker run through args.

High Availability

For users who want environment-specific high availability built into their Docker images.

Prerequisites

  • You've run applications in Docker and have experience building Docker images.

Service Tokens

Accessing your secrets in production or CI/CD environments requires a Service Token to provide read-only access to a specific config. It's exposed to the CLI via the DOPPLER_TOKEN environment variable which should be provided by your CI/CD environment, e.g. GitHub Secret.

Option 1: Dockerfile

This method installs the Doppler CLI installed in your Docker image to inject secrets at container runtime. It's a great option because your container orchestrator, docker run or docker-compose up command needs only a single DOPPLER_TOKEN environment variable.

Installing the CLI is a single command and works for all Linux containers.

# Install the Doppler CLI
RUN (curl -Ls https://cli.doppler.com/install.sh || wget -qO- https://cli.doppler.com/install.sh) | sh

Your Dockerfile will then need to use doppler run in either the ENTRYPOINT or CMD to fetch your secrets at container runtime. As a general rule, CMD is the easiest way to get started, but we'll explore both options below.

CMD method

Unless you're an experienced Docker user, we recommend using the CMD method.

CMD ["doppler", "run", "--", "printenv"]
  • Doesn't require understanding the difference between ENTRYPOINT and CMD
  • Good as it works with an existing ENTRYPOINT without requiring changes
  • Easily bypass the Doppler CLI by overriding theCMD at container runtime

ENTRYPOINT method

ENTRYPOINT ["doppler", "run", "--"]
CMD ["your-command-here"]
  • Good as it ensures any command used to run the container will have Doppler injected environment variables
  • Requires knowledge of ENTRYPOINT vs. CMD
  • Requires integrating into an existing ENTRYPOINT command or script if defined
  • Bypassing the use of the Doppler CLI in your ENTRYPOINT requires either conditional logic to only use Doppler if the DOPPLER_TOKEN environment variable is set, or overriding the ENTRYPOINT when running the container

πŸ“˜

Need more guidance? Reach out via in-product support or in our Community Portal

Example

Let's see a full example of a Dockerfile using the CMD option.

FROM alpine

# Install the Doppler CLI
RUN (curl -Ls https://cli.doppler.com/install.sh || wget -qO- https://cli.doppler.com/install.sh) | sh

# Fetch and view secrets using "printenv". Testing purposes only!
# Replace "printenv" with the command used to start your app, e.g. "npm", "start"
CMD ["doppler", "run", "--", "printenv"]

Because the contents of your Dockerfile has changed, you'll need to re-build it before continuing. If following along with this example, you'll need to build the image:

docker build -t doppler-test .

Now run the container:

# `DOPPLER_TOKEN` (Service Token) provided by CI/CD environment
docker run --rm -it --init -e DOPPLER_TOKEN="$DOPPLER_TOKEN" doppler-test
doppler setup # Select the project and config

# Use local Doppler configuration, passing in CLI token, project, and config
docker run --rm -it --init \
   -e "DOPPLER_TOKEN=$(doppler configure get token --plain)" \
   -e "DOPPLER_PROJECT=$(doppler configure get project --plain)" \
   -e "DOPPLER_CONFIG=$(doppler configure get config --plain)" \
   doppler-test

You should see your secrets output amongst the other container environment variables.


Option 2: Container Env Vars

Alternatively, the Doppler CLI can be used to supply environment variables to the container using the docker run --env-file flag combined with doppler secrets download.

This method requires a bash shell (for process substitution) and the Doppler CLI to be installed in the environment running the container. Using the alpine image as an example:

docker run --rm --env-file <(doppler secrets download --no-file --format docker) alpine printenv

You should now see your secrets output amongst the other container environment variables.

πŸ“˜

Docker does not support multi-line secrets when using the --env-file option so Doppler's --format docker flag flattens multi-line secrets by escaping newlines. These can then be converted back to their original form in your application code by replacing the escaped newlines with newlines (replace \\n with \n).


Option 3: High Availability

In the rare event that Doppler is down, you can optionally add high availability to your Docker images by creating an encrypted snapshot of the secrets at build time. This also allows images to be built for specific environments that do not require network access to the Doppler API as the Doppler CLI will fallback to the saved encrypted snapshot.

Please note that if you intend to use Doppler without network access during runtime, the DOPPLER_TOKEN will still need to be provided as it is used as the decryption key for the encrypted snapshot.

🚧

Using high availability will embed a snapshot of your config's secrets in the image. This image is now dedicated to that config and should not be reused across environments.

Let's see a full example of a Dockerfile with high availability:

FROM alpine

# Install the Doppler CLI
RUN (curl -Ls https://cli.doppler.com/install.sh || wget -qO- https://cli.doppler.com/install.sh) | sh

# Pass `DOPPLER_TOKEN` at build time to create an encrypted snapshot for high-availability
ARG DOPPLER_TOKEN

# Create encrypted snapshot for high availability
RUN doppler secrets download doppler.encrypted.json

# Fetch secrets and print them using "printenv" command
ENTRYPOINT ["doppler", "run", "--fallback=doppler.encrypted.json", "--"]
CMD ["your-command-here"]
FROM alpine

# Install the Doppler CLI
RUN (curl -Ls https://cli.doppler.com/install.sh || wget -qO- https://cli.doppler.com/install.sh) | sh

# Pass `DOPPLER_TOKEN` at build time to create an encrypted snapshot for high-availability
ARG DOPPLER_TOKEN

# Create encrypted snapshot for high availability
RUN doppler secrets download doppler.encrypted.json

# Fetch secrets and print them using "printenv" command
CMD ["doppler", "run", "--fallback=doppler.encrypted.json", "--", "your-command-here"]

🚧

High RPS?

If you are deploying this image to serverless infrastructure like Lambda or CloudRun that results in high RPS (+120 req/min) to Doppler's API, we recommend setting the --fallback-only flag on the doppler run command in the ENTRYPOINT.

# Read secrets from the snapshot and print them using "printenv" command
# Fetch secrets and print them using "printenv" command
ENTRYPOINT ["doppler", "run", "--fallback=doppler.encrypted.json", "--fallback-only", "--"]
CMD ["your-command-here"]
# Read secrets from the snapshot and print them using "printenv" command
CMD ["doppler", "run", "--fallback=doppler.encrypted.json", "--fallback-only", "--", "your-command-here"]

The DOPPLER_TOKEN is then passed in as a build-arg when building the image:

docker build --build-arg "DOPPLER_TOKEN=$DOPPLER_TOKEN" -t doppler-ha .

πŸ‘

Amazing Work!

Now you know 4 methods for using Doppler for managing app secrets and configuration in Docker.

Updated 3 months ago


Docker


reading time 5 mins

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.