Documentation

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

Get Started    Discussions

Docker

reading time 5 mins

Doppler simplifies configuring Docker applications by requiring only a single DOPPLER_TOKEN environment variable and the Doppler CLI to provide the latest version of all application config and secrets at runtime.

This guide will show you how to use Doppler for config and secrets in Docker for production and local development.

Prerequisites

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

Install

Installing the Doppler CLI is easy thanks to our one-line install script:

RUN (curl -Ls https://cli.doppler.com/install.sh || wget -qO- https://cli.doppler.com/install.sh) | sh

If on the other hand you're new to Docker, check out our Docker Base Image Guide.

Usage

Your Dockerfile will now need to use doppler run in the ENTRYPOINT to fetch your secrets at container runtime:

ENTRYPOINT ["doppler", "run", "--"]
CMD ["your-command-here"]

Setting the ENTRYPOINT to use doppler run provides the benefit that the command used to run the container (via CMD or an override with docker run), will have access to Doppler secrets as environment variables automatically.

Example

Let's see a full example of a Dockerfile:

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 secrets and print them using "printenv" command
ENTRYPOINT ["doppler", "run", "--"]
CMD ["your-command-here"]

Because the contents of your Dockerfile has changed, you'll need to re-build it before continuing.

To access your secrets when running the container, Doppler needs read-only access to a specific config using a Service Token via the DOPPLER_TOKEN environment variable:

docker run --rm -it --init -e "DOPPLER_TOKEN=$DOPPLER_TOKEN" doppler-test

πŸ“˜

When using a custom Docker image, run your container with the --init flag.

This allows the Docker container to be run and configured for any environment at runtime.

Local Development

You can use your local Doppler configuration when running your container. In this case, we are providing the project and config credentials as well, since a CLI token is being used:

doppler setup # Select the 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

High Availability (Optional)

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.

# 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", "--"]

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"]

🚧

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"]

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 how to use Doppler for managing app secrets and configuration in Docker, from local development to production.

Updated 13 days 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.