What Is the Docker .env File and How Do You Use It?

When you deploy Docker containers, you will oftentimes have to add customized variables. Those variables could include all sorts of information, including usernames, passwords, database names, etc. Of course, you can always hard code those variables into the container manifest but that is widely considered a security issue. On top of that, if you’re deploying similar containers over and over again, it’s not exactly efficient having to re-type all of that information.

To solve these types of problems, most developers opt to go with the .env file. Essentially, an .env file is a list of key pair values that set specific variables for a container deployment. So, instead of having to code those variables into the manifest itself, you add them to an .env file and when you run docker-compose up -d, the variables will be applied from within the .env file (“env” being short for environment variables).

It really is that straightforward.

The .env file can be used for simple container deployments and even complex full-stack deployments. Either way, it’s a much more secure way of using secrets for a deployment. Although nothing is perfect, using a hidden file (one that starts with a . in Linux is considered hidden) that keeps you from hard coding secrets into your manifests should not just be considered the smart way to go, it should be your default. And, yes, there are even more secure ways to handle secrets.

A few things to keep in mind about .env files:

• The .env file is used during the pre-processing step with docker-compose.yml files.
• To pass variables from the .env file to the command, you use $ as in $DB_DATABASE.
• ENV values are available via docker-build or run-style commands (using the $ as explained above).
• ENV files allow you to pass multiple environment variables at once.
• You can pass the .env file variables to the docker run command using the –env-file options, like so: docker run –env-file .env mysql:latest

For example, you can create a new Docker secret like this:

First, create a file that contains a secret with:

Next, create the Docker secret with:

The output will be something like this:

You can list your secrets with the command:

The output will contain the secret you just created like so:

You could then use that secret when deploying a service like this:

The output of the above command will look something like this:

There are also third-party services, such as HashiCorp Vault, that offer encrypted vaults that can be used to house secrets.

But if you’re looking to simplify things, the .env file is a great way to go. On top of which, the .env file isn’t just about keeping secrets. With this file, you can add any environment variable that you need.

Let me show you how to create one.

Creating Your First .env File

Let’s say you’ve created a directory to house all of your working files for the project, called ~/my-project. Change into that directory with the command cd ~/my-project. In that directory, create the .env file with the command:

Remember, the .env file must be contained within the base directory of your project, otherwise, it won’t be picked up by the deploy command.

A very basic .env file might contain the following key pairs:

Let’s say, however, you’re deploying a stack that includes a MySQL database container and you need to set the database server, database port, database name, database username, and database password. That .env file might look something like this:

Save that file with the [Ctrl]+[X] keyboard shortcut. Now, your YAML file will need to be set up properly. Let’s simplify this a bit. Say our .env file looks like this:

To pass those variables to our docker-compose.yml file, that file would have to contain something like this:

When you run the docker-compose up -d command, the environment key values will be passed to the deployment and things should spin up nicely, without having to save those values in the docker-compose.yml file.

This is also very handy in that you can create a single .env file to repurpose for other deployments. This is especially so when creating complex deployments. I would, however, advise not saving secrets in these files on your local storage. You could always create .env files to be reused, with placeholders for passwords, like so:

When you go to use that .env file, copy it into the base directory of the project, substitute the actual passwords, save the file, and then run your docker-compose command.

Of course, nothing is perfectly secure. Should something gain access to the machine housing the .env files, all they would have to do is issue the command ls -la within the directory housing the .env file to verify there is an environment variable file and then view the contents with something like cat .env. When you’re dealing with highly sensitive information, your best bet is to use a third-party service, such as the aforementioned HashiCorp Vault. But for your standard Docker deployments, the .env file is a great way to go.