Docker Compose down بمقابلہ stop: اصل فرق کیا ہے؟

مختصر جواب

docker compose stop کنٹینرز کو روک دیتا ہے اور انہیں disk پر برقرار رکھتا ہے۔ docker compose down کنٹینرز کو روکتا ہے، پھر کنٹینرز اور اس project کے لیے Compose کے بنائے ہوئے network کو حذف کر دیتا ہے۔ دونوں میں سے کوئی بھی command named volume کو متاثر نہیں کرتی۔ -v شامل کرنے سے، جیسا کہ docker compose down -v میں ہے، Compose file کے volumes section میں اعلان کردہ اور اس project سے متعلق non-external named volumes حذف ہو جاتے ہیں۔ down جس چیز کو واقعی ضائع کرتا ہے وہ ہر container کی اپنی writable layer میں لکھی گئی ہر چیز ہے، جو کسی volume کے باہر ہو۔

یہی پورا فرق ایک paragraph میں ہے۔ اس guide کے باقی حصے میں Postgres volume کے ذریعے ثابت کیا گیا ہے کہ وہ down کے بعد برقرار رہتا ہے اور down -v کے تحت حذف ہو جاتا ہے۔ اس میں یہ بھی بتایا گیا ہے کہ کن دو صورتوں میں --force-recreate درکار ہوتا ہے۔

docker compose stop: کنٹینرز رک گئے ہیں، مگر موجود ہیں

stop ہر کنٹینر کے مرکزی process کو، بطور ڈیفالٹ، configured stop signal یعنی SIGTERM بھیجتا ہے، انتظار کرتا ہے، اور اگر process اب بھی چل رہا ہو تو SIGKILL بھیج دیتا ہے۔ انتظار کی ڈیفالٹ مدت 10 سیکنڈ ہے اور -t اسے تبدیل کرتا ہے۔ کچھ بھی delete نہیں ہوتا۔ کنٹینر اپنی ID، writable layer اور logs برقرار رکھتا ہے۔

docker compose stop
docker compose ps -a

docker compose ps اکیلے صرف running containers دکھاتا ہے، اس لیے stop کے بعد یہ خالی table دکھاتا ہے اور لوگ سمجھتے ہیں کہ کنٹینرز ختم ہو گئے ہیں۔ ps -a stopped containers بھی شامل کرتا ہے۔ وہاں ہر service کے ساتھ Exited status اور اس process کا exit code نظر آتا ہے۔ صاف طور پر بند ہونے پر عموماً Exited (0) دکھائی دیتا ہے، لیکن ہمیشہ نہیں۔ کچھ servers graceful shutdown مکمل کرنے کے بعد stop signal دوبارہ process کو بھیجتے ہیں، جس سے process اسی signal کے باعث ختم ہوتا ہے۔ Uvicorn بھی یہی کرتا ہے، اس لیے orderly stop کے باوجود non-zero code رہ سکتا ہے۔ non-zero code اس بات کی بھی نشاندہی کر سکتا ہے کہ process ناکام ہوا یا timeout کے بعد ختم کیا گیا۔ docker compose start سے انہیں دوبارہ چلائیں۔ یہ بالکل وہی containers دوبارہ استعمال کرتا ہے۔

چونکہ containers اب بھی موجود ہیں، اس لیے volume کے باہر ان کے اندر لکھی گئی ہر چیز برقرار رہتی ہے۔ اس میں وہ package بھی شامل ہے جسے آپ نے docker compose exec سے دستی طور پر install کیا ہو، اور وہ config file بھی جس میں آپ نے container کے اندر ترمیم کی ہو۔ debugging کے دوران stop کو ترجیح دینے کی عملی وجہ یہی ہے: آپ اسی state میں دوبارہ start کر سکتے ہیں۔

docker compose down: containers اور networks حذف کر دیے جاتے ہیں

down پہلے containers کو روکتا ہے، پھر انہیں حذف کر دیتا ہے۔ اس کے ساتھ وہ default network بھی حذف ہو جاتا ہے جسے Compose نے project کے لیے بنایا تھا۔ Docker documentation کے مطابق یہ containers کو روکنے اور up کے ذریعے بنائے گئے containers، networks، volumes اور images کو حذف کرنے کا کام کرتا ہے۔ تاہم volumes اور images صرف اس وقت حذف ہوتے ہیں جب آپ بالترتیب -v اور --rmi استعمال کرنے کو کہیں۔

docker compose down
docker compose ps -a
docker network ls

down کے بعد ps -a project کے لیے کچھ بھی print نہیں کرتا، اور <project>_default network موجود نہیں رہتا۔ Project name عموماً project directory کے نام سے آتا ہے، جب تک کہ آپ Compose file میں name: set نہ کریں، COMPOSE_PROJECT_NAME set نہ کریں، یا -p pass نہ کریں۔ Container کی writable layer میں کی گئی ہر تبدیلی اب ناقابل بازیافت ہے۔ اس لیے down کو ایسی command سمجھیں جو container کو ضائع کر دیتی ہے، جبکہ volumes میں محفوظ کیا گیا data برقرار رہتا ہے۔

اگر Compose کو موجودہ directory یا اس کی parent directories میں configuration file نہ ملے، اور آپ نے -f یا COMPOSE_FILE کے ذریعے کوئی file فراہم نہ کی ہو، تو no configuration file provided: not found ظاہر ہوتا ہے۔ Compose کو معلوم نہیں ہوتا کہ آپ کا مطلب کون سا project ہے، اس لیے یہ command چلانے سے انکار کر دیتا ہے۔ جب آپ project folder میں موجود نہ ہوں تو docker compose -f /srv/myapp/compose.yaml down استعمال کریں۔

کیا docker compose down میرے volumes حذف کر دیتا ہے؟

نہیں۔ اعلیٰ سطح کی volumes key کے تحت بیان کیا گیا named volume، down کے بعد بھی برقرار رہتا ہے اور اس container کے بعد بھی موجود رہتا ہے جس کے ساتھ وہ منسلک تھا۔ اس command کے بارے میں یہی سب سے عام خدشہ ہے۔ Compose v5.7.0 نے down -v تبدیل کیا ہے: اب یہ کسی دوسرے project سے تعلق رکھنے والے یا Compose کے باہر بنائے گئے named volumes کو warning کے ساتھ چھوڑ دیتا ہے۔

ایسا stack تیار کریں جسے آپ آزما سکیں۔ اسے ایک خالی directory میں compose.yaml کے اندر رکھیں، جس کا نام voltest ہو۔

services:
  db:
    image: postgres:16.4
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

اسے شروع کریں اور ایک ایسی row لکھیں جسے آپ بعد میں پہچان سکیں۔

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "create table marker (note text);"
docker compose exec -T db psql -U postgres -c "insert into marker values ('survived');"

اب container کو حذف کریں اور volume چیک کریں۔

docker compose down
docker volume ls

Output میں اب بھی voltest_pgdata درج ہے۔ container ختم ہو گیا ہے، لیکن data موجود ہے۔ stack دوبارہ شروع کریں اور row پڑھیں۔

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "select * from marker;"

آپ کو survived پر مشتمل ایک row ملے گی۔ نیا container الگ ID والا مختلف container ہے، جو اسی volume کے ساتھ منسلک ہے۔ اگر آپ مکمل تصویر دیکھنا چاہتے ہیں تو Compose basics guide میں named volumes کا bind mounts کے ساتھ تقابل اور یہ وضاحت شامل ہے کہ ہر volume host پر حقیقتاً کہاں موجود رہتا ہے۔

down -v در حقیقت کیا حذف کرتا ہے

-v (طویل صورت --volumes) Compose فائل کے volumes سیکشن میں اعلان کردہ، اس project سے متعلق non-external named volumes کو حذف کرتا ہے۔ یہ containers سے منسلک anonymous volumes بھی حذف کرتا ہے۔ Compose v5.7.0 میں ایسا named volume جس پر کسی دوسرے project کا ownership label ہو، یا کوئی project label نہ ہو، warning کے ساتھ چھوڑ دیا جاتا ہے؛ اگر اس کی ownership کی جانچ نہ ہو سکے تو command ناکام ہو جاتی ہے اور volume برقرار رہتا ہے۔ اسے اسی stack پر چلائیں۔

docker compose down -v
docker volume ls

voltest_pgdata اب فہرست میں موجود نہیں ہے۔ Stack دوبارہ شروع کریں تو Postgres entrypoint کو خالی data directory ملتی ہے، اس لیے وہ نیا cluster initialize کرتا ہے۔ Container log یہ بات واضح الفاظ میں بتاتا ہے۔

The files belonging to this database system will be owned by user "postgres".
PostgreSQL init process complete; ready for start up.

کئی ماہ سے چلنے والے stack میں یہ block نظر آنے کا مطلب ہے کہ Postgres خالی data directory initialize کر رہا ہے۔ آپ کا marker table ختم ہو چکا ہے، اور واپس آنے کا واحد طریقہ backup ہے۔

کچھ storage -v سے کبھی حذف نہیں ہوتا۔ Bind mount، host path ہوتا ہے، اس لیے Docker صرف اسے unmount کرتا ہے اور آپ کی files اپنی جگہ برقرار رہتی ہیں۔ external: true سے نشان زدہ volume کے بارے میں اعلان ہوتا ہے کہ وہ اس project سے باہر کسی چیز سے متعلق ہے، اس لیے Compose اسے کبھی حذف نہیں کرتا۔ اگر down -v چلانے سے پہلے آپ نے named volume کو Compose file سے حذف کر دیا ہو تو وہ اب declared نہیں رہتا۔ Compose اسے حذف کرنے کے لیے نہیں پہچانتا، اور کسی container کے اس کا حوالہ دینا بند کرنے کے بعد وہ docker volume prune -a کے لیے orphan کے طور پر موجود رہتا ہے۔

آخری صورت refactor کے دوران لوگوں کو مشکل میں ڈالتی ہے۔ File سے service اور اس کا volume حذف کریں، پھر down -v چلائیں، تو volume برقرار رہتا ہے کیونکہ file میں اب اس کا ذکر نہیں ہے۔ File میں ترمیم کرنے سے پہلے down -v چلائیں، بعد میں نہیں۔

جب --force-recreate درکار ہو

docker compose up -d ہر بار پوری تعیناتی دوبارہ نہیں بناتا۔ Compose ہر سروس کی resolved configuration کا hash container پر label کے طور پر محفوظ کرتا ہے۔ Compose v5.7.0 میں running container کو اسی وقت برقرار رکھا جاتا ہے جب configuration hash، image ID اور image-volume digest یکساں ہوں، متوقع network connections اور named volume mounts موجود ہوں، اور namespace یا volume sharing والا کوئی parent دوبارہ نہ بنایا جا رہا ہو۔ اس صورت میں Recreated کے بجائے Container voltest-db-1 Running ملتا ہے۔ تقریباً ہمیشہ یہی مطلوبہ رویہ ہے، کیونکہ اس سے up -d کو بار بار محفوظ طریقے سے چلایا جا سکتا ہے۔

اسی وجہ سے بعض edits کا کوئی اثر دکھائی نہیں دیتا۔ Compose ان files کے contents کا hash نہیں بناتا جن کی طرف service definition اشارہ کرتی ہے؛ وہ resolved service definition کا hash بناتا ہے۔ Container میں mount کی گئی config file کو اگر startup پر صرف ایک بار پڑھا جائے تو اسے edit کرنے سے recreate trigger نہیں ہوتا، کیونکہ mount path تبدیل نہیں ہوا۔ سروس چلتی رہتی ہے اور boot کے وقت پڑھی گئی values استعمال کرتی ہے۔

docker compose up -d --force-recreate

یہ ہر container کو stop اور remove کرکے اسی definition سے نیا container بناتا ہے۔ Mounted config file میں edit کے بعد، یا جب container ایسی حالت میں پہنچ جائے جس کی وضاحت نہ کی جا سکے، اسے استعمال کریں۔ Volumes میں کوئی تبدیلی نہیں ہوتی، اس لیے force recreate کے بعد database برقرار رہتا ہے۔ اسی tag پر موجود نئی image حاصل کرنے کے لیے pull بھی درکار ہے۔

docker compose pull
docker compose up -d

pull نئی image ID حاصل کرتا ہے، اور پھر up -d running container کی image ID سے مختلف image ID دیکھ کر خود اسے recreate کرتا ہے۔ pull کے بغیر --force-recreate شامل کرنے سے وہی پرانی image استعمال کرتے ہوئے نیا container بنتا ہے۔ اسی لیے "میں نے force recreate کیا، لیکن version اب بھی پرانا ہے" ایک عام شکایت ہے۔

docker compose restart ان میں سے کچھ بھی نہیں کرتا۔ یہ موجودہ containers کو restart کرتا ہے، لیکن ان کی configuration میں تبدیلیاں لاگو نہیں کرتا۔ اس لیے بدلا ہوا environment variable یا بدلی ہوئی port mapping نافذ نہیں ہوگی۔ اگر آپ نے file edit کی ہے تو up -d استعمال کریں۔

ذہنی ماڈل جسے برقرار رکھنا ہے

Containers کو تبدیل کیا جا سکتا ہے۔ Container ایک process اور ایک باریک writable layer پر مشتمل ہوتا ہے، اور Compose file اور image سے replacement تیار کر سکتا ہے۔ Volumes کو تبدیل نہیں کیا جا سکتا، کیونکہ state کی واحد copy ان میں موجود ہوتی ہے، اور repository کی کوئی file اسے دوبارہ تیار نہیں کر سکتی۔

Compose کا ہر verb اسی تقسیم کے مطابق کام کرتا ہے۔ stop اور start container برقرار رکھتے ہیں۔ down اور up container کو تبدیل کرتے ہیں اور volume برقرار رکھتے ہیں۔ down -v واحد معمول کا command ہے جو state حذف کرتا ہے، اسی لیے اسے explicit flag درکار ہوتا ہے۔ کسی حقیقی environment میں اسے چلانے سے پہلے تصدیق کریں کہ آپ کے پاس backup موجود ہے اور آپ نے اسے کم از کم ایک بار restore کیا ہے۔

یہی منطق secrets پر بھی لاگو ہوتی ہے۔ POSTGRES_PASSWORD کے ذریعے set کیا گیا password صرف database کے پہلی بار initialize ہونے پر database password set کرنے کے لیے استعمال ہوتا ہے، اس لیے environment file میں اسے تبدیل کرنے اور up -d چلانے سے stored password تبدیل نہیں ہوتا۔ Container نیا ہوتا ہے، جبکہ volume پرانا رہتا ہے، اور پرانے volume میں اب بھی پرانا password موجود ہوتا ہے۔ Compose env files اور secrets کو کیسے resolve کرتا ہے وضاحت کرتا ہے کہ ایک ہی variable دو بار set ہونے پر کون سی layer کو ترجیح ملتی ہے۔

خرابی کی صورتیں اور نظر آنے والے پیغامات

no configuration file provided: not found کا مطلب ہے کہ Compose کو موجودہ directory اور اس کی parent directory میں تلاش کے ذریعے configuration file نہیں ملی، یعنی -f یا COMPOSE_FILE۔ مکمل path کے ساتھ -f فراہم کریں۔

Compose v5.7.0 میں down پر Network voltest_default Resource is still in use کا مطلب ہے کہ containers اب بھی project network سے منسلک ہیں۔ عموماً یہ وہ containers ہوتے ہیں جو اس project کے باہر دستی طور پر docker run --network کے ذریعے شروع کیے گئے تھے۔ ان containers کو ہٹائیں، پھر دوبارہ down چلائیں۔

Found orphan containers (voltest-old-1) for this project اس وقت ظاہر ہوتا ہے جب آپ کسی service کا نام تبدیل یا اسے حذف کرتے ہیں۔ موجودہ Compose ناموں کو سادہ صورت میں، comma سے جدا کر کے دکھاتا ہے۔ پرانے Compose v2 releases یہی warning ناموں کو square brackets میں دکھا کر جاری کرتے ہیں، جیسا کہ ([voltest-old-1]) میں ہے۔ پرانا container اب بھی project label رکھتا ہے۔ docker compose down --remove-orphans انہیں صاف کر دیتا ہے۔

دستی طور پر docker volume rm چلانے پر Error response from daemon: remove voltest_pgdata: volume is in use کا مطلب ہے کہ کوئی container اب بھی volume کو reference کر رہا ہے، جس میں stopped container بھی شامل ہے۔ پہلے docker compose down چلائیں، پھر volume ہٹائیں، یا براہ راست down -v استعمال کریں۔ بڑے project میں multi service Compose stack دکھاتا ہے کہ ایک project میں کتنے volumes جمع ہو سکتے ہیں۔

FAQ

کیا docker compose down میرا database حذف کر دیتا ہے؟

نہیں، اگر database کسی named volume یا bind mount میں موجود ہو۔ down containers اور project network کو ہٹا دیتا ہے، جبکہ volume اپنی data کے ساتھ disk پر برقرار رہتا ہے۔ اگلا docker compose up -d اسی volume کے ساتھ نیا container attach کرتا ہے، اور data موجود رہتی ہے۔ docker compose down -v Compose file کے volumes section میں declared non-external named volumes کو ہٹا دیتا ہے، بشرطیکہ وہ اسی project سے متعلق ہوں۔

جس container کو میں دوبارہ چلانا چاہتا ہوں، اس کے لیے stop اور down میں کیا فرق ہے؟

stop container کو برقرار رکھتا ہے، اس لیے docker compose start آپ کو اسی container اور اسی writable layer پر واپس لے آتا ہے۔ آپ نے container کے اندر دستی طور پر جو کچھ install یا edit کیا ہے، وہ برقرار رہتا ہے۔ down container کو حذف کر دیتا ہے، اس لیے اگلا up -d image سے نیا container بناتا ہے اور وہ دستی تبدیلیاں ضائع ہو جاتی ہیں۔ Debugging کے دوران stop استعمال کریں۔

Compose project کی بنائی ہوئی ہر چیز کیسے ہٹاؤں؟

docker compose down -v --rmi all --remove-orphans containers، project network، file میں declared اور اسی project سے متعلق non-external named volumes، services کے استعمال کردہ images، اور project کے orphan containers کو ہٹا دیتا ہے۔ یہ bind mounts یا external: true سے marked volumes کو متاثر نہیں کرتا۔ اسے چلانے سے پہلے docker volume ls کے ذریعے دیکھیں کہ کون سی چیزیں حذف ہونے والی ہیں۔

میرا container mounted config file میں کی گئی تبدیلی کو نظر انداز کیوں کرتا ہے؟

Compose resolved service definition کے hash کا موازنہ کر کے فیصلہ کرتا ہے کہ container دوبارہ بنانا ہے یا نہیں، اور اس hash میں mounted file کا content شامل نہیں ہوتا۔ Path تبدیل نہیں ہوا، اس لیے Compose container کو چلتا رہنے دیتا ہے اور وہی values استعمال ہوتی ہیں جو startup کے وقت پڑھی گئی تھیں۔ File دوبارہ پڑھنے والا نیا container بنانے کے لیے docker compose up -d --force-recreate چلائیں۔

POSTGRES_PASSWORD تبدیل کرنے کے بعد نئی value کام کیوں نہیں کر رہی؟

Postgres image database password مقرر کرنے کے لیے POSTGRES_PASSWORD صرف اس وقت استعمال کرتی ہے جب وہ empty data directory کو initialise کرتی ہے۔ آپ کے volume میں cluster پہلے ہی initialised ہے، اس لیے variable نظر انداز ہوتی ہے اور پرانا password برقرار رہتا ہے۔ نئی password کے ساتھ connect کرنے پر password authentication failed for user "postgres" ملتا ہے۔ چلتے ہوئے database کے اندر ALTER USER کے ذریعے password تبدیل کریں، یا data ضائع ہونے کی صورت میں docker compose down -v کے ذریعے دوبارہ شروع کریں۔