From 9656895b60e85aeee82a599dc601813ba815b0df Mon Sep 17 00:00:00 2001
From: GPla <36087062+GPla@users.noreply.github.com>
Date: Sat, 24 Aug 2024 22:04:30 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20note=20in=20Docker=20docs?=
 =?UTF-8?q?=20about=20ensuring=20graceful=20shutdowns=20and=20lifespan=20e?=
 =?UTF-8?q?vents=20with=20`CMD`=20exec=20form=20(#11960)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: svlandeg <svlandeg@github.com>
Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com>
---
 docs/en/docs/deployment/docker.md | 32 +++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/en/docs/deployment/docker.md b/docs/en/docs/deployment/docker.md
index 253e25fe5..ab1c2201f 100644
--- a/docs/en/docs/deployment/docker.md
+++ b/docs/en/docs/deployment/docker.md
@@ -232,6 +232,38 @@ Review what each line does by clicking each number bubble in the code. 👆
 
 ///
 
+/// warning
+
+Make sure to **always** use the **exec form** of the `CMD` instruction, as explained below.
+
+///
+
+#### Use `CMD` - Exec Form
+
+The <a href="https://docs.docker.com/reference/dockerfile/#cmd" class="external-link" target="_blank">`CMD`</a> Docker instruction can be written using two forms:
+
+✅ **Exec** form:
+
+```Dockerfile
+# ✅ Do this
+CMD ["fastapi", "run", "app/main.py", "--port", "80"]
+```
+
+⛔️ **Shell** form:
+
+```Dockerfile
+# ⛔️ Don't do this
+CMD fastapi run app/main.py --port 80
+```
+
+Make sure to always use the **exec** form to ensure that FastAPI can shutdown gracefully and [lifespan events](../advanced/events.md){.internal-link target=_blank} are triggered.
+
+You can read more about it in the <a href="https://docs.docker.com/reference/dockerfile/#shell-and-exec-form" class="external-link" target="_blank">Docker docs for shell and exec form</a>.
+
+This can be quite noticeable when using `docker compose`. See this Docker Compose FAQ section for more technical details: <a href="https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop" class="external-link" target="_blank">Why do my services take 10 seconds to recreate or stop?</a>.
+
+#### Directory Structure
+
 You should now have a directory structure like:
 
 ```