ההבדל בין command ל-entrypoint ב-Docker Compose
למדו איך entrypoint ו-command עובדים יחד ב-Docker Compose. גלו את ארבעת השילובים האפשריים והבינו מדוע הגדרת entrypoint מוחקת את ה-CMD המקורי של ה-image שלכם.
ההבדל בין command לבין entrypoint ב-Docker Compose, בכלל אחד
ב-Docker Compose, הערך entrypoint: מגדיר את התוכנית שתרוץ, והערך command: מגדיר את הארגומנטים שיועברו לתוכנית זו. התהליך של המכולה מורכב מרשימת ה-entrypoint בצירוף רשימת ה-command בסופה. כל התנהגות אחרת המתוארת בדף זה נובעת ממשפט יחיד זה.
שני המפתחות הללו ממופים לשתי הוראות ב-Dockerfile. הערך entrypoint: מחליף את ה-ENTRYPOINT של ה-image. הערך command: מחליף את ה-CMD של ה-image. הם אינם בלתי תלויים, וזהו המקום שבו משתמשים נתקלים בקשיים: הגדרת entrypoint: מוחקת גם את ה-CMD של ה-image. מפרט ה-Compose קובע זאת במפורש. אם entrypoint אינו ריק, Compose מתעלם מכל פקודת ברירת מחדל שמגיעה מה-image.
קרא את מה שהאימג' כבר מגדיר
לפני שאתה דורס הגדרות כלשהן, בדוק מה האימג' מספק כברירת מחדל.
docker image inspect --format '{{json .Config.Entrypoint}}' postgres:16
docker image inspect --format '{{json .Config.Cmd}}' postgres:16אתה מקבל את ["docker-entrypoint.sh"] ואת ["postgres"], כך שהקונטיינר מריץ את docker-entrypoint.sh postgres. הסקריפט הזה יוצר את ספריית הנתונים בעלייה הראשונה, קורא את משתני ה-POSTGRES_*, מוריד הרשאות למשתמש postgres, ולבסוף מריץ את הארגומנטים שניתנו לו. ההחלטה כולה תלויה בהבנה איזה חלק ברצונך לשנות. כדי להעביר flag למסד הנתונים, עליך להחליף את command:. אם תחליף את entrypoint:, שום חלק מתהליך ההגדרה הזה לא יתבצע כלל.
ארבעת השילובים, מוצגים בתמונה קטנה
בנו image שתפקידו היחיד הוא להדפיס את רשימת הארגומנטים שאיתה הוא הופעל.
FROM alpine:3.20
ENTRYPOINT ["/bin/echo", "ep"]
CMD ["cmd"]docker build -t argdemo .services:
demo:
image: argdemoהריצו את docker compose up לאחר כל עריכה וקראו את השורה הבודדת שהוא מתעד ביומן.
- אף מפתח אינו מוגדר. התהליך הוא
/bin/echo ep cmdוהיומן מציגep cmd. command: ["cmd2"]בלבד. התהליך הוא/bin/echo ep cmd2. ה-entrypoint נותר ללא שינוי ורק הארגומנטים השתנו.entrypoint: ["/bin/echo", "ep2"]בלבד. התהליך הוא/bin/echo ep2והיומן מציגep2. ה-cmdמה-image נעלם, ושום דבר לא מזהיר אתכם מכך.- שני המפתחות מוגדרים. התהליך הוא
/bin/echo ep2 cmd2. זהו המקרה היחיד שבו אתם שולטים בכל רשימת הארגומנטים.
מדוע הגדרת entrypoint מוחקת את ה-CMD של ה-image
ה-CMD של image נכתב כרשימת הארגומנטים המוגדרת כברירת מחדל עבור ה-ENTRYPOINT של אותו image. אם תחליפו את ה-entrypoint, הארגומנטים הללו ישויכו לתוכנית שכבר אינה רצה, ולכן Compose מסיר אותם במקום לבנות שורת פקודה שיוצר ה-image מעולם לא התכוון שתתקיים. docker run --entrypoint מתנהג באותו אופן, כך שמדובר בהתנהגות של Docker ולא במאפיין ייחודי של Compose.
התוצאה היא מוחשית. nginx:1.27 מצהיר על ENTRYPOINT ["/docker-entrypoint.sh"] ועל CMD ["nginx", "-g", "daemon off;"]. הגדירו entrypoint: /custom-init.sh והסקריפט שלכם יתחיל עם רשימת ארגומנטים ריקה. סקריפט שמסתיים ב-exec "$@" הרגיל ימצא שאין לו מה להריץ (exec), לכן exec לא יבצע דבר, הסקריפט יגיע לשורתו האחרונה, וה-container יסתיים עם קוד 0 ללא הודעת שגיאה בשום מקום. החזירו את הארגומנטים בעצמכם:
services:
web:
image: nginx:1.27
entrypoint: /custom-init.sh
command: ["nginx", "-g", "daemon off;"]הכלל שיש לזכור: בכל פעם שאתם מגדירים entrypoint:, החליטו מה צריך להיות ה-command: באותה עריכה.
פורמט exec ופורמט shell, וההבדלים ב-Compose
קובץ Dockerfile מקבל שתי תחבירים. CMD ["nginx", "-g", "daemon off;"] הוא פורמט exec: הבינארי רץ ישירות, ללא מעורבות של shell. CMD nginx -g "daemon off;" הוא פורמט shell: Docker משכתב אותו כ-/bin/sh -c 'nginx -g "daemon off;"', כך ש-shell רץ תחילה והתוכנית שלכם הופכת לצאצא שלו.
Compose אינו מעתיק את הכלל הזה, וזה מפתיע משתמשים רבים. מחרוזת ב-command: מפוצלת לארגומנטים ומבוצעת ישירות, ללא מעטפת /bin/sh -c. התיעוד של Compose מפורש בנושא: השדה command אינו רץ בתוך ההקשר של SHELL המוגדר ב-image, לכן אם אתם זקוקים ליכולות של shell, עליכם להפעיל shell בעצמכם.
זו הסיבה ש-command: echo "hello $$HOSTNAME" מדפיס את הטקסט המילולי hello $HOSTNAME. אף shell לא ראה את המחרוזת, ולכן דבר לא עבר הרחבה (expansion). בקשו shell במפורש כאשר אתם זקוקים לאחד כזה:
services:
demo:
image: alpine:3.20
command: /bin/sh -c 'echo "hello $$HOSTNAME"'אותות (Signals), PID 1, ופקודת docker compose down תקינה
docker compose stop ו-docker compose down שולחים את אות העצירה של הקונטיינר ל-PID 1 בתוך כל קונטיינר. האות הוא SIGTERM, אלא אם ה-STOPSIGNAL של האימג' או ה-stop_signal: של השירות מגדירים אחרת. לאחר מכן, Compose ממתין עד stop_grace_period ושולח SIGKILL רק אם הקונטיינר עדיין רץ. תקופת החסד (grace period) המוגדרת כברירת מחדל היא 10 שניות.
PID 1 הוא תהליך מיוחד ב-Linux. תהליך ה-init של מרחב שמות (namespace) של PID מקבל אותות רגילים מתהליכים אחרים רק אם הותקן עבורם מטפל (handler); לכן, תהליך שלא התקין מטפל ל-SIGTERM פשוט מתעלם מ-SIGTERM כשהוא רץ כ-PID 1. SIGKILL ו-SIGSTOP שנשלחים ממרחב שמות אב הם יוצאי דופן: הם מסיימים או עוצרים את PID 1 בכוח, בהתאמה. התהליך נשאר במצבו למשך כל תקופת החסד ואז נקטל מיד, מה שקוטע כל חיבור פתוח או טרנזקציה שלא הושלמה.
שימוש ב-shell לפני התוכנית שלכם הופך מצב זה לסביר יותר, כיוון שה-shell הוא PID 1 ורוב ה-shells אינם מעבירים אותות לתהליכי בת. חלק מה-shells מחליפים את עצמם בפקודה הסופית במחרוזת -c, כך שלעיתים התוכנית שלכם מגיעה ל-PID 1 בכל זאת. זה תלוי ב-shell ובמחרוזת המדויקת, לכן אל תנחשו. בדקו זאת:
docker compose exec -T web cat /proc/1/cmdline | tr '\0' ' '; echoאם ה-PID 1 המודפס הוא /bin/sh -c ... במקום התוכנית שלכם, יש שני פתרונות. השתמשו ב-exec form באימג', או השאירו את ה-shell והעבירו את התהליך בעזרת exec:
services:
web:
image: myapp:1.4
command: /bin/sh -c 'exec myapp --config /etc/myapp.toml'exec מחליף את תהליך ה-shell בתוכנית שלכם במקום ליצור תהליך בת (fork), כך שהתוכנית שלכם יורשת את PID 1 ומקבלת את האות.
תוכניות מסוימות יוצרות תהליכי בת ולעולם לא אוספות אותם (reap), מה שמשאיר תהליכי זומבי, כיוון ש-PID 1 הוא גם האחראי על האיסוף. ל-Compose יש מתג עבור זה:
services:
web:
image: myapp:1.4
init: true
stop_grace_period: 30sinit: true מריץ תהליך init קטן כ-PID 1 שמעביר אותות לתוכנית שלכם ואוסף תהליכי בת. stop_grace_period נותן לכיבוי איטי באמת יותר מרחב פעולה. אם התוכנית שלכם מצפה לאות אחר, stop_signal: SIGQUIT משנה את מה ש-Compose שולח. בדקו מה האימג' מבקש כבר עכשיו בעזרת docker image inspect --format '{{.Config.StopSignal}}' nginx:1.27.
סטאק שבו docker compose down לוקח תמיד עשר שניות לכל שירות מאותת לכם לבדוק האם PID 1 מטפל באות העצירה המוגדר, והאם הכיבוי דורש יותר זמן מתקופת החסד. תקנו זאת לפני שתאשימו את הכלים, ועיינו ב-ההבדל בין docker compose down ל-stop כדי להבין מה כל תת-פקודה מסירה.
אותה חלוקה בין exec ל-shell מופיעה במקום נוסף. בדיקת תקינות (healthcheck) שנכתבה כ-test: ["CMD", "curl", "-f", "http://localhost/"] מריצה את הבינארי ישירות, בעוד ש-test: ["CMD-SHELL", "curl -f http://localhost/ || exit 1"] מריצה אותו דרך shell כך ש-|| מקבל משמעות. כתיבת בדיקות תקינות ל-Compose שנכשלות בצורה אמינה מכסה את שאר הנושא הזה.
הוספת דגל לתמונה רשמית
זהו הנושא שרוב הקוראים הגיעו עבורו. אתם מעוניינים בדגל נוסף עבור postgres, ואסור לכם לשבש את סקריפט האתחול.
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- pgdata:/var/lib/postgresql/data
command: postgres -c max_connections=200 -c shared_buffers=256MB
volumes:
pgdata:רק command: השתנה, לכן docker-entrypoint.sh עדיין רץ ומבצע את מה שהעברתם לו. בדקו את התוצאה במקום להניח שהיא תקינה:
docker compose up -d db
docker compose exec -T db psql -U postgres -c 'show max_connections;'הפלט אמור להציג את 200. אם הוא עדיין מציג את 100, הריצו את docker compose config וודאו שה־command שאתם מצפים לו נמצא בפלט הממוזג. המנגנון של Compose ממזג קובצי override על ידי החלפה מוחלטת של command, ולא על ידי הוספה אליו; לכן, קובץ שני שמגדיר גם הוא את command: ינצח בשקט.
ה־${POSTGRES_PASSWORD} שלעיל מורחב על ידי Compose במארח מתוך קובץ ה-.env שלכם, עוד לפני שהמכולה קיימת. קובצי סביבה וסודות ב-Compose מכסה היכן ערך זה יכול להישמר בצורה בטוחה.
הרצת פעולת מיגרציה חד-פעמית עם docker compose run
docker compose run בונה מכולה חדשה על בסיס הגדרת השירות הקיימת ומחליף את הפקודה בכל מה שתקלידו לאחר שם השירות. ה-entrypoint של האימג' עדיין רץ, כך שהמכולה מוכנה בדיוק כמו המכולה שרצה באופן קבוע.
docker compose run --rm app python manage.py migrate--rmמוחק את המכולה עם סיום הפקודה. בלעדיו, כל הרצה משאירה מאחור מכולה עצורה, שניתן לראות ב-docker compose ps -a.- פורטים אינם מפורסמים. מכולת
runמתעלמת מה-ports:של השירות אלא אם תוסיפו--service-ports, ולכן היא לא יכולה להתנגש עם השירות שכבר פעיל. - תלויות עולות קודם. כל מה שמוגדר ב-
depends_onיעלה לפני הפקודה שלכם, ו---no-depsמדלג על שלב זה. - המכולה מקבלת שם שנוצר אוטומטית כמו
myproject-app-run-9f2c1a, כך שהיא לעולם לא תתנגש עם מכולת השירות.
כדי להחליף גם את ה-entrypoint, קיים דגל ייעודי לכך:
docker compose run --rm --entrypoint /bin/sh app -c 'python manage.py migrate'רשימת הארגומנטים המתקבלת היא /bin/sh -c 'python manage.py migrate', כיוון שהמילים שאחרי שם השירות הן עדיין הפקודה. docker compose exec הוא הכלי השני והוא עובד אחרת: הוא מריץ תהליך בתוך מכולה שכבר פעילה, והוא מתעלם לחלוטין מ-entrypoint: ומ-command:. השתמשו ב-run עבור משימה שזקוקה למכולה חדשה, וב-exec כדי לבדוק מה קורה בתוך מכולה פעילה. ה-דף עזר לפקודות Compose מציג את שאר תתי-הפקודות זו לצד זו.
מדוע המכולה שלי נסגרת מיד?
התחילו בבדיקת קוד היציאה (exit code), שכן הוא מצמצם את טווח הסיבות האפשריות במהירות.
docker compose ps -a
docker compose logs appקוד יציאה 0 ללא פלט. הפקודה רצה והסתיימה. הסיבה הנפוצה ביותר היא דריסה (override) של entrypoint: שלקחה איתה את ה-CMD של האימג', כך שה-entrypoint רץ עם רשימת ארגומנטים ריקה ולא היה לו מה להריץ.
שגיאה המסתיימת ב-permission denied. לסקריפט אין הרשאת הרצה (executable bit) בתוך האימג', בדרך כלל משום שההרשאה לא הוגדרה מעולם על הקובץ במאגר (repository). הגדירו אותה בזמן הבנייה באמצעות COPY --chmod=0755 entrypoint.sh /entrypoint.sh.
שגיאה המסתיימת ב-no such file or directory עבור קובץ שניתן לראות בבירור באימג'. לסקריפט יש סיומות שורות של Windows. השורה הראשונה שלו נקראת כ-#!/bin/sh בתוספת בייט של carriage return, לכן ה-kernel מחפש מפרש (interpreter) עם הבייט הזה בשמו ולא מוצא דבר. הריצו את dos2unix entrypoint.sh, ולאחר מכן הוסיפו את * text eol=lf ל-.gitattributes כדי שהבעיה לא תחזור.
executable file not found in $PATH. התוכנית שצוינה ב-command: אינה נמצאת באף תיקייה ב-PATH של המכולה. או שהאימג' לא מכיל אותה, או שהיא מותקנת במקום מחוץ ל-PATH (כתבו את הנתיב המלא שלה במקום), או שכתבתם פקודה מובנית של ה-shell כמו cd במקום שבו יכולה לעבוד רק תוכנית אמיתית.
קבלת גישה ל-shell במכולה שה-entrypoint שלה נכשל
כאשר ה-entrypoint קורס לפני שניתן לבדוק דבר מה, החליפו אותו:
docker compose run --rm --entrypoint /bin/sh appאם פעולה זו נכשלת עם stat /bin/sh: no such file or directory, סימן שלתמונה אין /bin/sh. תמונות מסוג Distroless ותמונות המבוססות על scratch לרוב אינן כוללות shell כלל. עדיין ניתן לקרוא את מערכת הקבצים מבחוץ מבלי להפעיל את ה-entrypoint:
docker create --name probe myapp:1.4
docker export probe | tar -tv | head -40
docker rm probeכאשר יש צורך להשאיר את המכולה פעילה כדי להתחבר אליה שוב ושוב, השאירו אותה רצה על תהליך שלעולם אינו מסתיים. הוסיפו זאת לקובץ override שאינכם מבצעים לו commit:
services:
app:
entrypoint: ["tail", "-f", "/dev/null"]
command: []command: [] אינו נחוץ באופן מחייב, שכן הגדרת entrypoint: כבר ניקתה את ה-CMD של התמונה, אך כתיבתו מתעדת את הכוונה עבור מי שיקרא את הקובץ בהמשך. העלו את המכולה והיכנסו פנימה:
docker compose -f compose.yaml -f compose.debug.yaml up -d app
docker compose exec app /bin/shכעת הריצו את ה-entrypoint האמיתי באופן ידני וצפו היכן הוא נעצר. כך תקבלו את הודעת השגיאה בטרמינל שלכם במקום בתוך מכולה שקרסה לפני חצי שנייה. אם אתם עדיין בונים את ה-stack הראשון שלכם, stack ראשון של Compose ב-VPS מכסה את מבנה הקבצים שכל האמור לעיל מניח.
FAQ
מדוע המכולה שלי נסגרת מיד לאחר הרצת docker compose up?
בדקו את docker compose ps -a כדי לראות את קוד היציאה. יציאה 0 ללא פלט מעידה בדרך כלל על כך שהגדרתם entrypoint: בשירות, מה שמחק גם את ה-CMD של האימג', ולכן ה-entrypoint רץ עם רשימת ארגומנטים ריקה והסתיים. הוסיפו את הארגומנטים בחזרה באמצעות command:. שגיאה שמסתיימת ב-permission denied מציינת שלסקריפט ה-entrypoint אין הרשאת הרצה (executable bit). שגיאה שמסתיימת ב-no such file or directory עבור קובץ שקיים בפועל, מעידה על כך שלסקריפט יש סיומות שורות בסגנון Windows, ולכן שורת ה-shebang שלו מצביעה על מפרש שאינו קיים.
האם הגדרת entrypoint ב-Compose מסירה את ה-CMD של האימג'?
כן. אם ה-entrypoint אינו ריק, Compose מתעלם מכל פקודת ברירת מחדל שהוגדרה באימג'. זו התנהגות מתועדת התואמת ל-docker run --entrypoint. הסיבה לכך היא שה-CMD של אימג' נכתב כארגומנטים עבור ה-ENTRYPOINT של אותו אימג', כך שברגע שמחליפים את ה-entrypoint, הארגומנטים הישנים אינם שייכים עוד לשום דבר. הגדירו command: באותו שירות אם ה-entrypoint החדש עדיין זקוק לארגומנטים.
האם מחרוזת בפקודת Compose מורצת דרך shell?
לא. בניגוד ל-CMD ב-Dockerfile, מחרוזת ב-command: של Compose מפוצלת לארגומנטים ומבוצעת ישירות, ללא מעטפת /bin/sh -c. לכן, Compose לעולם לא מפעיל shell בתוך המכולה כדי להרחיב עבורכם $VARIABLE. קראו ל-shell בעצמכם כאשר אתם זקוקים לו, כפי שמוצג ב-command: /bin/sh -c 'echo "hello $$HOSTNAME"'. ה-$$ הכפול מבצע escape לסימן הדולר, כך ש-Compose מעביר אותו למכולה במקום להרחיב אותו על המארח.
מדוע docker compose down לוקח עשר שניות עבור מכולה אחת?
Compose שולח את אות העצירה ל-PID 1 (אלא אם האימג' או השירות מגדירים אחרת, SIGTERM), ממתין עד stop_grace_period (10 שניות כברירת מחדל), ואז שולח SIGKILL אם המכולה עדיין רצה. תהליך ה-init של מרחב שמות PID מתעלם מ-SIGTERM ללא handler, ולכן הוא ממתין את מלוא פרק הזמן; SIGKILL ו-SIGSTOP ממרחב שמות PID אב הם חריגים שמסיימים או עוצרים אותו בכוח. גלו מהו ה-PID 1 האמיתי באמצעות docker compose exec -T app cat /proc/1/cmdline | tr '\0' ' '. אם מדובר ב-shell, העבירו את האימג' לפורמט exec או כתבו exec בתוך מחרוזת ה-shell. אם התהליך יוצר תהליכי-בן (children) שהוא לעולם לא אוסף (reap), הגדירו init: true בשירות.