Documentation

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

Get Started    Discussions

Docker

reading time 35 mins

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.

Doppler Base Image

When constructing your Dockerfile, it is recommended to use the official Doppler base image. The base images come in a couple of flavors depending on what other dependencies you have.

Image NameDescription
dopplerhq/cliAlpine base image (alpine)
dopplerhq/cli:nodeNode 12 image (node:lts-alpine)
dopplerhq/cli:pythonPython 3 image (python:3-alpine)
dopplerhq/cli:rubyRuby 2 image (ruby:2-alpine)

Versioning

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.

Image NameVersion LevelUpdates you'll receive
dopplerhq/cliLatest- Breaking changes
- All new features
- Bug fixes
dopplerhq/cli:3Major (recommended)- New, backwards-compatible features
- Bug fixes
dopplerhq/cli:3.1Minor- Bug fixes
dopplerhq/cli:3.1.0Patch (not recommended)- None

Dockerfile

Now let's put all this together with a sample Dockerfile. This Dockerfile will:

  1. Use the alpine base image.
  2. Instruct Docker to expect 3 Doppler credentials as build arguments.
  3. Configure the Doppler CLI to use those credentials.
  4. Cache secrets from Enclave at build time, which will later be used for high availability.
  5. Fetch the latest version of secrets from Enclave 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 ENCLAVE_PROJECT
ARG ENCLAVE_CONFIG

# 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 -- ./your-comand-here

Using a Different Base Image

If you would like to use a different base image, you can install the Doppler CLI with our shell script.

# 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

Changing the User

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 configure set 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 enclave setup --no-prompt --silent

Running Multiple Commands

You may need to chain together multiple commands using built-in shell operators (&&, ||, ;, etc.). To use these operators, you must pass in your command in quotes with the --command flag.

The example below will always execute ./first-command, will execute ./second-command if the first command succeeds (exit code 0), and will always execute ./cleanup-command.

ENTRYPOINT doppler run --command="./first-command && ./second-command; ./cleanup-command"

Building the Image

When building your Docker image you must supply 1 build argument. This argument is a token that authorizes the CLI to fetch secrets from Enclave. Since in most cases a service token will be used, the Enclave project and config credentials do not need to be provided, as a service token can only access one config.

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 Enclave 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 "ENCLAVE_PROJECT=$(doppler configure get enclave.project --plain)" \
   --build-arg "ENCLAVE_CONFIG=$(doppler configure get enclave.config --plain)"

Running the Image

Now let's run the newly built doppler-test image.

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

One-off Commands

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.

CLIDocker
Commanddopplerdocker run --rm -it dopplerhq/cli:3

Let's take a look at a quick example. For this example, we are going to use the Doppler alpine image to fetch secrets from Enclave. 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 \
   enclave secrets --token $DOPPLER_TOKEN

Docker Compose

If you are using Docker Compose to run multiple containers at the same time, there a couple things you may want to change to support Doppler. The first step is to create a script to manage it, which will fetch the Doppler credentials in local development from the Doppler CLI, run the build command, and then clean up any lingering artifacts and containers.

#!/bin/bash

# Fetch Doppler Credentials when in Local Development
if [ -z "$DOPPLER_TOKEN" ]; then
  export DOPPLER_TOKEN=$(doppler configure get token --plain --silent)
fi

if [ -z "$ENCLAVE_PROJECT" ]; then
  export ENCLAVE_PROJECT=$(doppler configure get enclave.project --plain --silent)
fi

if [ -z "$ENCLAVE_CONFIG" ]; then
  export ENCLAVE_PROJECT=$(doppler configure get enclave.config --plain --silent)
fi

# Start Docker Compose
docker-compose \
  -f tests/e2e/docker-compose.yml \
  --project-directory . \
  up \
  --build;

# Capture Exit Code
EXIT_CODE=$?

# Cleanup Docker Compose
docker-compose \
  -f docker-compose.yml \
  --project-directory . \
  rm \
  -fsv;

# Exit with Code
exit $EXIT_CODE

Next, we need to modify your docker-compose.yml file to pass in the Doppler credentials to the Dockerfile as build arguments.

services:
  web:
    build:
      dockerfile: Dockerfile
      context: .
      args:
        DOPPLER_TOKEN: "$DOPPLER_TOKEN"
        ENCLAVE_PROJECT: "$ENCLAVE_PROJECT"
        ENCLAVE_CONFIG: "$ENCLAVE_CONFIG"

Predefined Entrypoint

Some Docker images have a predefined entrypoint script and expect you to specify your application start script through the command parameter. To do this correctly with Doppler you will want to move the doppler run command out of the entrypoint and into the docker-compose.yml file.

services:
  web:
    build:
      dockerfile: Dockerfile
      context: .
      args:
        DOPPLER_TOKEN: "$DOPPLER_TOKEN"
        ENCLAVE_PROJECT: "$ENCLAVE_PROJECT"
        ENCLAVE_CONFIG: "$ENCLAVE_CONFIG"
    command: doppler run -- ./your-comand-here

👍

Amazing Work!

Next, let's set up authentication with Doppler for staging & production with Service Tokens.

Updated 15 days ago


Docker


reading time 35 mins

Suggested Edits are limited on API Reference Pages

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