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

This article has been updated from when it was originally published on January 24, 2023

Overview

The article discusses the use of the .env file in Docker container deployments. A .env file is a text file that contains key-value pairs representing environment variables that can be used by containers during deployment.

Key points:

• The .env file allows developers to set environment variables without hardcoding them into the container manifest, making it a more secure approach.
• Environment variables in the .env file are referenced using $ followed by the variable name (e.g., $DB_DATABASE) in docker-compose.yml files.
• The .env file can be used for simple and complex deployments, including full-stack deployments.

Benefits:

• Simplifies managing configuration across different environments
• Promotes better security by not hardcoding sensitive information into source code repositories or docker-compose files
• Allows developers to create reusable .env files with placeholders for passwords

Best practices:

• Keep the .env file in a separate directory from your project’s working files.
• Use third-party services like HashiCorp Vault for highly sensitive information.
• Avoid saving secrets in local storage and use secure methods to manage them.

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:

echo "this-is-my-secret" > $HOME/secret.txt

Next, create the Docker secret with:

docker secret create password-secret $HOME/secret.txt

The output will be something like this:

fx0ziezaw0xjpb0i7bt092xmi

You can list your secrets with the command:

docker secret list

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

fx0ziezaw0xjpb0i7bt092xmi password-secret 48 seconds ago 48 seconds ago

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

docker service create --name test-service --secret password-secret mysql:latest

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

zcoz2b2xvzakoq1x7jny6l5x5
overall progress: 1 out of 1 tasks
1/1: running
verify: Service converged

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:

nano .env

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:

USERNAME=olivia
PASSWORD=b3stp@$$w0rd

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:

DB_HOST="127.0.0.1"
DB_PORT="3306"
MYSQL_ROOT_PASSWORD="r00tp@$$w0rd"
DB_USER="dbuser"
DB_PASSWORD="p@$$w0rd"
DB_DATABSE="database"

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:

MYSQL_ROOT_PASSWORD="r00tp@$$w0rd"
MYSQL_ALLOW_EMPTY_PASSWORD="p@$$w0rd"
MYSQL_RANDOM_ROOT_PASSWORD="p@$$w0rd"

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

MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
MYSQL_ALLOW_EMPTY_PASSWORD: ${MYSQL_ALLOW_EMPTY_PASSWORD}
MYSQL_RANDOM_ROOT_PASSWORD:  ${MYSQL_RANDOM_ROOT_PASSWORD}

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:

MYSQL_ROOT_PASSWORD="ROOT_PWORD"
MYSQL_ALLOW_EMPTY_PASSWORD="PASSWORD"
MYSQL_RANDOM_ROOT_PASSWORD="PASSWORD"

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.

FAQ

Q: What is the recommended way to store sensitive information in a Docker container? 

A: Store sensitive information such as passwords, API keys, and credentials in an environment variable file (.env file) outside of your code repository. This ensures that sensitive data is not committed to version control.

Q: What is the best way to manage environment variables for my Docker container? 

A: Use an environment variable file (.env file) or a secrets manager like HashiCorp Vault. This ensures that sensitive information is properly secured and isolated from other parts of your application.

Q: How do I secure my Docker container from unauthorized access? 

A: Use a combination of methods, such as:

• Configure SELinux (or AppArmor) policies.
• Limit network traffic and ports exposed.
• Regularly update your containers to prevent exploitation of known vulnerabilities.

Q: How can I ensure that my Docker containers are running with the correct permissions? 

A: Set the security-options, no-new-privileges, apparmor-enabled to limit privileges and enforce AppArmor or SELinux policies. Additionally, use User Namespaces (UN) to isolate processes from each other.

Q: What is the recommended way to update my Docker containers with new dependencies? 

A: Use a tool like Docker Compose or Kubernetes’ rolling updates feature to roll out changes gradually, ensuring minimal disruption to your application.

Q: How can I optimize performance in my Docker container? 

A: Optimize resource allocation by:

• Limiting CPU and memory usage
• Using caching mechanisms (e.g., Redis)
• Minimizing network traffic
• Leveraging content delivery networks (CDNs) for static assets

Q: What is the best way to test and validate my Docker containers? 

A: Use automated testing frameworks like CI/CD tools, such as Jenkins or Travis CI. Additionally, perform manual testing by running your application in a non-production environment.

Q: How can I ensure that my Docker container complies with security standards?

A: Follow established guidelines and best practices for securing containers, such as the following:

• Regularly update dependencies to prevent exploitation of known vulnerabilities
• Implement secure protocols (HTTPS) for communication
• Limit access to sensitive data and resources

Q: What is the recommended way to store Docker container logs? 

A: Use a centralized logging solution like Fluentd, ELK Stack, or Splunk. This ensures that log analysis can be performed efficiently and provides visibility into container activity.

Q: How can I ensure that my Docker containers are properly backed up and restored? 

A: Implement regular backups of your containers using tools like Docker’s built-in backup feature (such as the docker commit command) or third-party solutions like Backblaze B2.