diff --git a/_data/toc.yaml b/_data/toc.yaml
index ab70cbcc2b..7f5da9d235 100644
--- a/_data/toc.yaml
+++ b/_data/toc.yaml
@@ -1413,8 +1413,12 @@ manuals:
title: Uninstall Docker Compose
- path: /compose/gettingstarted/
title: Getting started
- - path: /compose/environment-variables/
- title: Environment variables in Compose
+ - sectiontitle: Environment variables
+ section:
+ - path: /compose/environment-variables/
+ title: Overview
+ - path: /compose/envvars-precedence/
+ title: Environment variables' precedence
- path: /compose/env-file/
title: Environment file
- path: /compose/profiles/
diff --git a/compose/envvars-precedence.md b/compose/envvars-precedence.md
new file mode 100644
index 0000000000..45ba8c6fe9
--- /dev/null
+++ b/compose/envvars-precedence.md
@@ -0,0 +1,40 @@
+---
+title: Environment variables precedence
+description: TODO
+keywords: compose, environment, env file
+---
+
+
+
+- Command Line (docker compose run --env https://docs.docker.com/engine/reference/commandline/compose_run/#options)
+- Compose File (service::environment section: https://docs.docker.com/compose/compose-file/#environment)
+- Compose File (service::env_file section file: https://docs.docker.com/compose/compose-file/#env_file)
+- Container Image ENV directive (https://docs.docker.com/engine/reference/builder/#env)
+
+When `WHEREAMI` is the variable in case:
+
+| Image (`ENV` directive in Dockerfile) | OS Environment | `.env` file on the project root (or overwrite through `docker compose -–env-file `) | Compose file (`service::env_file`) | Compose file (`service::environment`) | Command line (docker compose run -e ) | RESULT |
+|:-------------------------------------:|:-----------------:|:-----------------------------------------------------------------------------------------:|:----------------------------------:|:-----------------------------------------:|:------------------------------------------------:|:------------------------:|
+| Dockerfile
| OS_Env | WHEREAMI=DotEnv_File | | | | Dockerfile |
+| Dockerfile | OS_Env | WHEREAMI=DotEnv_File
| | | WHEREAMI | DotEnv_File |
+| Dockerfile | OS_Env
| WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | | WHEREAMI | OS_Env |
+| Dockerfile
| OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | | | Dockerfile |
+| Dockerfile | | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue
} | | | WHEREAMI | DotEnv_File_DefaultValue |
+| Dockerfile | OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | | WHEREAMI=Command_Line
| Command_Line |
+| Dockerfile | OS_Env
| WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI | | OS_Env |
+| Dockerfile | OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI=Environment_Section
| | Environment_Section |
+| Dockerfile | OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI=Environment_Section | WHEREAMI=Command_Line
| Command_Line |
+| Dockerfile | OS_Env
| WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI=Environment_Section | WHEREAMI | OS_Env |
+| Dockerfile | OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI | WHEREAMI=Command_Line
| Command_Line |
+| Dockerfile | OS_Env | | WHEREAMI=Env_File | | WHEREAMI=Command_Line
| Command_Line |
+| Dockerfile | OS_Env | | WHEREAMI=Env_File | WHEREAMI=Environment_Section
| | Environment_Section |
+| Dockerfile | OS_Env | | WHEREAMI=Env_File
| | | Env_File |
+| Dockerfile | OS_Env
| | | WHEREAMI=${WHEREAMI:-Environment_Section} | | OS_Env |
+| Dockerfile | OS_Env
| WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI=${WHEREAMI:-Environment_Section} | | OS_Env |