Stop Using .env Files: Docker Secrets Made Easy with Doppler

One of the things that gets “hard” when you start caring about the security of your Docker containers is managing your secrets. It is a tricky bit that you need to understand and handle with care as secrets are generally needed but they can open a can of worms if you aren’t careful, especially in production environments. This is where Doppler comes in. It is a solution that helps to secure your Docker secrets in a way that keeps these from being easily exposed. As a level set, this is not a paid post from Doppler and I have no affiliation with them. It is just a tool I used and wanted to let everyone know about.

What are secrets?

First, we need to understand what secrets are exactly. These are anything that contains sensitive information. The obvious one of course is passwords. But it can include API keys, cloud credentials, server names, IP addresses, database servers, database names, etc.

Really, anything that you wouldn’t want to fall in the wrong hands or be exposed. If an attacker could use that information to bring harm to your business or compromise critical systems, it is probably safe to say it is a “secret” that you need to protect.

Why docker secrets are a touchy subject

Most apps needs some form of secrets to authenticate with various resources. The problem is though that storing secrets incorrectly can be very dangerous. If secrets end up hard coded into your source code, that is bad. But equally bad is committing these to source, like a repo in GitHub.

These can end up in data breaches or major security risks. Even in a home lab, an exposed secret could mean that you compromise your cloud resources, have hijacked SaaS accounts or other very bad outcomes. For businesses, the impact can be even worse with compliance fines, lost customer confidence, or long recovery times due to breached data that was wiped out by an attacker.

Docker does have some native ways to handle secrets, especially if you are running Docker Swarm. However, this has limitations. Also, if you are running a standalone Docker host, you don’t have the capabilities that are offered in Docker Swarm. The gap between standalone docker hosts and Swarm leaves developers defaulting back to environment files that aren’t encrypted or centrally managed.

Why .env files are better but not great

I have blogged and said before that it is best practice to use .env files. And, when compared to hard coding your secrets in docker-compose, it is better. However. env files are also a problem since you have sensitive information in them as well. So, they usually wind up lingering on disk and not really being secured itself.

If someone gains access to the Docker host, they will be able to read the .env files. Also, if you forget to add your .env files to your .gitignore file, secrets may accidentally get pushed to public repos. Even in a private repo, sharing sensitive information in version control is not a good practice.

Also, managing multiple .env files for dev, staging, and production is tedious and painful. These have to be kept in sync manually or through a step in your pipeline.

What is Doppler?

I stumbled on Doppler when looking for an easy way to manage secrets between dev, test, and prod environments with a simple Docker app that was needed. It is a secrets management platform, not specifically just for Doppler, but for many other solutions as well.

It is built with developer in mind to make it easier for them to keep secrets out of their code and config files. Doppler lets you create environments that map to your apps. Each project you create has keys and values that you define like:

• DB_USER
• DB_PASSWORD
• API_KEY
• etc…

So, very familiar as these look just like what you would put in your .env files. However, instead of managing these manually in files scattered across environments, Doppler provides a way to have these stored in a central location and encrypted in a vault. Then, the secrets can be injected into your apps when they run.

This is one of the reasons I came to quickly really like it is that it integrates very easily with Docker and Docker-Compose workflows. This is an area where many people may struggle with secrets management.

Update once and in one place

The other nice thing that I like about it is that you update your secret in one place and once and the latest version is available everywhere you use it. So, if you rotate your passwords or API keys, you only have to do this once in Doppler. Then the connected apps will get it on the next run.

For businesses that want to have this available for teams, there are access controls that are in place as well as audit logs. You can see who changed things, when they did it, etc.

A quick home lab example of using Doppler with Docker Compose

As we know, proper Docker security is not just for production environments, it is also great for the home lab. And, what I like to do is actually do the things we do in production in the home lab as this reinforces best practices and just the mindset of doing things with security in mind.

After you sign up for a Doppler account and verify your email address, create a new project. Here I am creating a new “homelab” project.

You need to install Doppler on your Docker host so the host can interact with the Doppler service. You can do that with the commands below for Debian/Ubuntu. However, check out the documentation here for other OS’es: Install CLI.

# Debian 11+ / Ubuntu 22.04+
sudo apt-get update && sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -sLf --retry 3 --tlsv1.2 --proto "=https" 'https://packages.doppler.com/public/cli/gpg.DE2A7741A397C129.key' | sudo gpg --dearmor -o /usr/share/keyrings/doppler-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/doppler-archive-keyring.gpg] https://packages.doppler.com/public/cli/deb/debian any-version main" | sudo tee /etc/apt/sources.list.d/doppler-cli.list
sudo apt-get update && sudo apt-get install doppler

Here we are checking the version of the Doppler CLI after installing it.

Generating a service token

You can generate a service token for the project which will be used for authentication to the Doppler service. Under Access for your project > branch, click the + Generate for Service Tokens.

This will bring up the dialog box for Create Service Token. Here you can set the access it has, its expiration, etc.

Once you generate it, you need to copy it and store it safely as it will not be shown again.

Using the service token for doppler setup

Now, we need to run the command:

doppler setup -t <your token>

It will know the scope of the service token as you can see below. It already knows it is scoped to the “homelab” project and it is available for the “dev” config.

Testing the use of tokens in doppler

Now, I have a docker-compose.yml file that has a couple of configuration settings that need to be defined for Traefik. If you have set this up before, these will look familiar. I need to pass in my Cloudflare token and email to be able to generate a Let’s Encrypt certificate using DNS validation.

So, just like creating these in an .env file, I am instead doing this in Doppler.

After creating the key value pair for the variables, I can now run the doppler command to have it inject the credentials and sensitive information when it runs the docker compose up -d command:

doppler run -- docker compose up -d

You should see your docker compose code run just like it would with an .env file, except there is no .env file in use and no sensitive data stored anywhere in plain sight. Very cool!

Auditing token use

When you navigate to your service tokens and Access, you will see the logging that is viewable there. You will see when the token was last used, the access it has, when it was created, last used, valid until, action, etc.

Different plans offered and free home lab version

Doppler has three different plans they offer and the great thing is you can have free access for your home lab I think which will cover what most will want to do in testing and running a few projects using it.

• Developer – free for 3 users and then $8/mo per additional user. This is the one that you can have free access to for your home lab!
• Team – $21/mo per user
• Enterprise – custom pricing available for this tier depending on a company’s needs

Comparing Doppler to Alternatives

There are several alternatives to using Doppler with Docker that you may want to compare and consider. Below are a few of the most common options in this space.

Wrapping it up

If you are still relying on .env files or certainly if you are hard coding values into your docker-compose files, you are behind. Doppler is a solution that lets you have a free and easy way to inject your sensitive information into your Docker environment, even if you are not using Docker Swarm or something like Kubernetes which has the native secrets management. The Doppler Developer plan is free for up to 3 users so this is a great option to start using in your home lab environment. Let me know what you are currently using for Docker secrets management.