Docker and Compose
Docker Compose secrets vs environment variables
Keep credentials out of Compose files and understand when mounted secrets are safer than ordinary environment variables.
By AppLaunch Editorial · Reviewed 2026-08-25
Direct answer
Use a secret manager or Compose secrets for sensitive values when the application can read a mounted file. Environment variables are convenient but more easily exposed through configuration, diagnostics or child processes; never commit real values into the Compose file.
What this means in plain English
Passwords and API keys need a safer path than being typed into compose.yaml. Environment variables are easy for applications to read, but they can appear in configuration output, debugging tools or child processes. Compose secrets can provide a value as a mounted file instead.
The best method also depends on what the application supports. Whichever method you use, keep real values out of Git, give each service only the secrets it needs and write down how to replace a secret without rebuilding the entire world.
How should a container receive a credential?
| Source control | Contains names and wiring, never secret values |
|---|---|
| Runtime | Mounted secret file where supported |
| Rotation | Document how a changed value reaches and restarts consumers |
A simple example
The web container needs a database password, but the worker does not. The password is stored outside the repository and supplied only to the web container as a secret file. When it changes, the deployment updates that secret and restarts the one service that reads it.
What to do, step by step
1. List credentials and current exposure paths.
Start here before buying anything or changing several settings at once. It gives you a clear starting point based on source control: contains names and wiring, never secret values. Write the result down so you can compare it later.
2. Move values to an external secret source.
Use the same files, versions and settings that the real project will use. A quick test with an empty or different setup can look successful while completely missing the problem you are trying to solve.
3. Grant each service only the secrets it needs.
Try the busiest realistic situation, not the easiest one. Include the people, data, traffic or background work you genuinely expect, then watch for slowdowns and errors rather than relying on a single headline number.
4. Test rotation and removal.
Finish by checking the result against rotation: document how a changed value reaches and restarts consumers. Keep the old setting or release available until you know the change works and can be reversed safely.
One more useful tip
A .env file is not automatically secure. It is only a text file. If it contains real secrets, protect it from source control, backups with broad access and accidental output in support logs.
Common mistakes and how to avoid them
Using .env as proof of secrecy.
This gives a misleading or unsafe result because it leaves out source control. A better approach is to list credentials and current exposure paths, then check the result before making the change permanent.
Passing every secret to every container.
This gives a misleading or unsafe result because it leaves out runtime. A better approach is to move values to an external secret source, then check the result before making the change permanent.
Logging full environment during debugging.
This gives a misleading or unsafe result because it leaves out rotation. A better approach is to grant each service only the secrets it needs, then check the result before making the change permanent.
Words explained
- container
- A packaged, isolated way to run an application with the files and software it needs.
- Compose
- Docker Compose is a file-based way to describe several containers, their settings, storage and networks as one application.
- secret
- A password, token or key that must not be committed to source control or exposed to users.
Quick checklist
- List credentials and current exposure paths.
- Move values to an external secret source.
- Grant each service only the secrets it needs.
- Test rotation and removal.
Common questions
What is the simple answer?
Use a secret manager or Compose secrets for sensitive values when the application can read a mounted file. Environment variables are convenient but more easily exposed through configuration, diagnostics or child processes; never commit real values into the Compose file.
What should I check first?
Start with source control: contains names and wiring, never secret values. That is usually more useful than choosing from a marketing label or copying somebody else’s setting.
How can I make the change safely?
List credentials and current exposure paths. Then change one thing at a time, keep a backup or old version, and use the same real-world test after each change.
What is the easiest mistake to avoid?
Using .env as proof of secrecy. Avoiding that one mistake makes the rest of the comparison much more trustworthy.