From c7bfeba8cad10d027126f06ec781122c4244f7e8 Mon Sep 17 00:00:00 2001
From: Dean Chen <862469039@qq.com>
Date: Sat, 15 Aug 2026 21:38:16 +0500
Subject: [PATCH] docs: warn CMD sh -c needs exec for SIGTERM

Otherwise the shell stays PID 1 and docker stop just kills
the app. Same note we already have under ENTRYPOINT.

Signed-off-by: Dean Chen <862469039@qq.com>
---
 content/manuals/build/building/best-practices.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/content/manuals/build/building/best-practices.md b/content/manuals/build/building/best-practices.md
index f9485bb7f337..bf0881ca1d5a 100644
--- a/content/manuals/build/building/best-practices.md
+++ b/content/manuals/build/building/best-practices.md
@@ -518,6 +518,16 @@ conjunction with [`ENTRYPOINT`](/reference/dockerfile.md#entrypoint), unless
 you and your expected users are already quite familiar with how `ENTRYPOINT`
 works.
 
+If you only start a shell to expand variables, `exec` the real process so it
+becomes PID 1 and gets `SIGTERM` from `docker stop`. Without `exec`, `sh -c`
+swallows the signal and the app is just killed:
+
+```dockerfile
+CMD ["sh", "-c", "exec java $JAVA_OPTS -jar app.jar"]
+```
+
+Same idea as the [`ENTRYPOINT`](#entrypoint) helper-script note below.
+
 For more information about `CMD`, see [Dockerfile reference for the CMD instruction](/reference/dockerfile.md#cmd).
 
 ### EXPOSE