Dynamic TLS and SSL Certificates for Docker Compose with Doppler

Doppler makes managing secrets for Docker Compose applications easy. This post will cover a reasonably complex use case of using Doppler to supply SSL/TLS certificates in PEM format to an application.

Requirements

• Doppler CLI installed and authenticated
• Docker Compose installed

To follow along with this tutorial, click on the Import to Doppler button below to create the Doppler project containing the required variables, including the TLS certificate and key.

Creating the Certificate and Key Secrets in Doppler

Use either the Doppler dashboard to copy and paste in the contents of your certificate and key, or the Doppler CLI as follows:

1doppler secrets set CERT_PEM="$(cat ./tls.cert)"
2doppler secrets set KEY_PEM="$(cat ./tls.key)"

Docker Compose Environment Variables

Understanding Docker Compose environment variables can be confusing at first as variable expansion can happen on the host and inside the container.

For the most part, all you need to know is:

• Use ${VAR} if you want variables expanded on the host
• Use $${VAR} if you want variables expanded inside the container.

Below is an example docker-compose.yaml for testing purposes that mounts a TLS certificate and key and uses the Open SSL CLI to print the certificate's metadata to verify that the certificate value from Doppler was valid.

1version: '3.9'
2services:
3web:
4image: alpine
5container_name: doppler-pem-certificates
6working_dir: /usr/src/app
7init: true
8
9# Test command to validate the certificate
10command: ['/bin/sh', '-c', 'apk add openssl && openssl x509 -in $${DOCKER_SECRETS_DIR}/tls.cert -inform pem -noout -text']
11
12# Only variables explicitly defined will be passed through to the container
13environment:
14APP_URL: https://${HOSTNAME}:${PORT} # Example of creating a new environment variable using values from Doppler
15DOCKER_SECRETS_DIR: $DOCKER_SECRETS_DIR # Syntax for passing an envirionment variable form Doppler to the container
16
17# Generate tls.cert and tls.key files with Doppler CLI prior to running `docker-compose up`
18volumes:
19- $PWD/tls.cert:/usr/src/app/${DOCKER_SECRETS_DIR}/tls.cert
20- $PWD/tls.key:/usr/src/app/${DOCKER_SECRETS_DIR}/tls.key

NOTE: An optimization we could perform here is using Doppler's secret referencing to replace the creation of APP_URL in the docker-compose.yaml file, using the exact same syntax.

Using Doppler to Inject Environment Variables for Docker Compose

The most important thing to understand when using Doppler with Docker Compose is that only variables listed in the environment object (or list) will be passed through from Doppler to the container.

Once everything is in place, the Doppler CLI makes supplying environment variables, and certificates for Docker Compose a breeze, first extracting the certificate and key to the file system for mounting inside the container, then running docker-compose up:

1doppler secrets get CERT_PEM --plain > tls.cert
2doppler secrets get KEY_PEM --plain > tls.key
3doppler run -- docker-compose up;

Docker Compose Secrets Management in Production Environments

Configuring the Doppler CLI for a Virtual Machine in production is done by scoping a Doppler Service Token to the file system location of your application code. The DOPPLER_TOKEN environment variable is required and should be injected securely through your CI-CD system, e.g., GitHub Action secrets.

Below is code you can incorporate as part of a Cloud-Init User-Data script. It uses Ubuntu, but other CLI installation commands are available from the Doppler CLI Installation documentation:

1#!/bin/bash
2
3# Install the Doppler CLI
4apt-get update && apt-get install -y apt-transport-https ca-certificates curl gnupg
5curl -sLf --retry 3 --tlsv1.2 --proto "=https" 'https://packages.doppler.com/public/cli/gpg.DE2A7741A397C129.key' | apt-key add -
6echo "deb https://packages.doppler.com/public/cli/deb/debian any-version main" | tee /etc/apt/sources.list.d/doppler-cli.list
7apt-get update && apt-get install -y doppler
8
9# Scope service token to your application code directory
10
11doppler configure set token $DOPPLER_TOKEN --scope /home/ubuntu/your-app
12
13# Remove the Service Token set command from bash history to prevent leaking of raw service token value
14history -c

Summary

Awesome work! Now you know how to use Doppler with Docker Compose to simplify and securely manage secrets for your applications in any environment, from development to production.

Be sure to check out our Docker Compose documentation and reach out in our Doppler Community Forum if you need help.