Docker Compose میں PUID اور PGID کیا کرتے ہیں؟
PUID اور PGID Docker settings نہیں بلکہ linuxserver.io images کا entrypoint convention ہیں۔ جانیں bind mount فائلیں 911:911 کیوں بنتی ہیں اور درست ownership کیسے کریں۔
PUID اور PGID دراصل کیا ہیں
PUID اور PGID دو environment variables ہیں جنہیں بعض container images startup کے وقت پڑھتی ہیں۔ Docker خود انہیں کبھی نہیں دیکھتا۔ یہ ایک convention ہے، جسے linuxserver.io images اور کچھ دیگر images استعمال کرتی ہیں۔ اس لیے جو image انہیں پڑھنے کے لیے نہیں لکھی گئی ہو، وہ انہیں خاموشی سے نظرانداز کر دیتی ہے۔
linuxserver.io image کے اندر abc نام کا ایک user ہوتا ہے۔ اسے build time پر UID (user ID) 911 اور GID (group ID) 911 کے ساتھ بنایا جاتا ہے۔ Container root کے طور پر شروع ہوتا ہے، اپنے init scripts چلاتا ہے، اور ان میں سے ایک script application شروع ہونے سے پہلے اس user کی IDs تبدیل کرتی ہے:
groupmod -o -g "${PGID}" abc
usermod -o -u "${PUID}" abc-o flag ایسی ID استعمال کرنے کی اجازت دیتا ہے جو کہیں اور پہلے سے استعمال ہو رہی ہو۔ اس کے بعد init privileges کم کرتا ہے اور application کو abc کے طور پر چلاتا ہے۔ اس طرح Docker PUID=1000 کو کسی بھی دوسرے environment variable کی طرح container میں منتقل کرتا ہے اور خود اس پر کوئی کارروائی نہیں کرتا۔ یہ variable application شروع ہونے سے پہلے container کے اندر ایک user کی ID تبدیل کرتا ہے۔ اس کا مطلب ہے کہ user namespace remapping کے بغیر ایک standard rootful daemon میں نئی بننے والی files عموماً آپ کی disk پر 1000 کی ملکیت کے ساتھ محفوظ ہوتی ہیں۔ کسی پہلے سے موجود writable file میں لکھنے سے اس کا owner تبدیل نہیں ہوتا۔ Rootless Docker اس number کو تبدیل کر دیتا ہے، جیسا کہ آگے بیان کیا گیا ہے۔ PUID unset چھوڑنے پر abc کی value 911 برقرار رہتی ہے۔ اسی لیے unconfigured bind mount میں 911:911 کی ملکیت والی files جمع ہو جاتی ہیں۔
id کے ساتھ اپنے دونوں نمبرز حاصل کریں
یہ کمانڈ host پر اس صارف کے طور پر چلائیں جو data directories کا مالک ہے:
iduid=1000(deploy) gid=1000(deploy) groups=1000(deploy),27(sudo),988(docker)uid آپ کا PUID ہے اور gid آپ کا PGID ہے۔ اسکرپٹ کے لیے id -u اور id -g صرف متعلقہ نمبرز print کرتے ہیں۔ زیادہ تر نئی VPS images میں پہلا انسانی account 1000:1000 ہوتا ہے، لیکن اسے فرض نہ کریں۔ ID کی allocation موجودہ accounts اور configuration پر منحصر ہوتی ہے: rebuilt server دوبارہ 1000 allocate کر سکتا ہے، جبکہ بعد میں بننے والے account کو زیادہ دستیاب ID مل سکتی ہے۔ اگر آپ کی services اپنے login user کے بجائے dedicated service account کے تحت چلتی ہیں تو id thatuser چلائیں اور وہاں سے نمبرز حاصل کریں۔
آپ کی فائلیں 911:911 کے طور پر کیوں دکھائی دیتی ہیں
ls -l اس وقت نام کے بجائے عددی ID دکھاتا ہے جب اس ID سے مطابقت رکھنے والا کوئی host account موجود نہ ہو۔ اگر UID 911 سے مطابقت رکھنے والا کوئی host account موجود نہیں، تو دکھانے کے لیے کوئی نام نہیں ہے۔ ہر بار اعداد دیکھنے اور ابہام ختم کرنے کے لیے ls -ln استعمال کریں:
ls -ln /srv/appdata/sonarrdrwxr-xr-x 2 911 911 4096 Aug 7 09:12 Backups
-rw-r--r-- 1 911 911 512 Aug 7 09:12 config.xmlیہ output container کے built-in defaults سے مطابقت رکھتا ہے، لیکن صرف موجودہ فائلوں سے یہ ثابت نہیں ہوتا کہ application اب کس user کے طور پر چل رہی ہے۔ اس listing میں موجود config.xml وہ فائل بھی ہے جس میں authentication settings محفوظ ہوتی ہیں۔ یہ اس وقت اہم ہے جب آپ پہلی بار web UI کھولیں اور دیکھیں کہ Sonarr اور Radarr میں کوئی default username یا password موجود نہیں ہوتا۔ اندازہ لگانے کے بجائے container کے اندر سے اس کی تصدیق کریں:
docker exec sonarr id abc
docker compose logs sonarr | head -n 25linuxserver init اپنا نتیجہ startup log میں دو lines کے طور پر لکھتا ہے:
User UID: 911
User GID: 911اگر آپ کی Compose file میں PUID=1000 set کرنے کے بعد ان lines میں 911 دکھائی دے، تو چلنے والا container آپ کی set کی ہوئی value استعمال نہیں کر رہا۔ عام وجہ یہ ہے کہ آپ نے docker-compose.yml میں ترمیم کی اور پھر docker compose restart چلایا، جس نے موجودہ container کو اس کے اصل environment کے ساتھ دوبارہ استعمال کیا۔ Environment میں تبدیلیوں کے لیے docker compose up -d درکار ہے، جو container کو دوبارہ بناتا ہے۔ دوسری وجہ دانستہ رویہ ہے: جب کوئی image read-only یا non-root mode میں چلتی ہے، تو init مکمل طور پر renumbering چھوڑ دیتا ہے، چاہے variable container میں موجود ہو۔ read-only mode میں banner abc کی غیر تبدیل شدہ ID دکھاتا ہے؛ non-root mode میں یہ /run کے owner کو دکھاتا ہے۔
آپ container کی لکھی ہوئی file حذف کیوں نہیں کر سکتے
Kernel ناموں کا نہیں، صرف نمبروں کا موازنہ کرتا ہے۔ آپ کا shell UID 1000 کے طور پر چلتا ہے۔ یہ file UID 911 کی ہے۔ اسے رکھنے والی directory drwxr-xr-x ہے اور وہ بھی 911 کی ملکیت ہے، اس لیے group اور other کو read اور execute کی اجازت ملتی ہے، لیکن write کی نہیں۔ File حذف کرنے کے لیے خود file پر نہیں، بلکہ اس کی directory پر write permission درکار ہوتی ہے۔ اسی لیے یہ نتیجہ ملتا ہے، چاہے file خود بے ضرر دکھائی دے:
rm: cannot remove '/srv/appdata/sonarr/config.xml': Permission deniedWriting container کو دوسری سمت سے یہی رکاوٹ پیش آتی ہے۔ اگر host directory آپ کے user کی ملکیت ہو اور اس کا mode 755 ہو، جبکہ application 911 کے طور پر چل رہی ہو، تو اس کی پہلی write Permission denied کے ساتھ ناکام ہو جاتی ہے اور app اسے اپنی اصطلاحات میں رپورٹ کرتی ہے۔ Sonarr یا Radarr جیسی .NET application میں یہ UnauthorizedAccessException: Access to the path '/data/downloads' is denied کے طور پر ظاہر ہوتا ہے۔ File کے سامنے موجود permission string بتاتی ہے کہ permission sets میں سے کس کے مطابق آپ کی جانچ ہو رہی ہے۔ drwxr-xr-x کو درست طور پر پڑھنا ہی اس error کو پراسرار کے بجائے واضح بناتا ہے۔
یہ خاص طور پر bind mount کا مسئلہ ہے۔ جب Docker ایک empty named volume بناتا ہے اور اسے image میں پہلے سے موجود path پر mount کرتا ہے، تو وہ اس path کا content، ownership اور permission bits سمیت، volume میں copy کر دیتا ہے۔ یوں application کو ایسی directory ملتی ہے جس کی ملکیت پہلے ہی اس کے پاس ہوتی ہے۔ Bind mount کو یہ سلوک نہیں ملتا: Docker آپ کی host directory کو بالکل اسی حالت میں mount کرتا ہے جس حالت میں وہ موجود ہو۔ bind mount کب named volume سے بہتر ہوتا ہے اور کب نہیں یہ جاننے کی عملی وجوہات میں یہ فرق بھی شامل ہے۔
پہلے سے غلط directory کو درست کرنا
PUID اور PGID مقرر کرنے سے ایپلیکیشن کا آئندہ رویہ تبدیل ہوتا ہے۔ اس سے disk پر پہلے سے موجود ہر file خودکار طور پر درست نہیں ہوتی، اگرچہ init نیچے بیان کردہ مخصوص paths پر ownership درست کرتا ہے۔ stack کو stop کریں، ownership خود درست کریں، پھر اسے دوبارہ start کریں:
docker compose down
sudo chown -R 1000:1000 /srv/appdata/sonarr
docker compose up -dاگر آپ numbers خود type نہیں کرنا چاہتے تو sudo chown -R "$(id -u):$(id -g)" /srv/appdata/sonarr استعمال کریں۔ یہ کام container کے stopped ہونے پر کریں، کیونکہ recursive chown کے دوران اگر running application file لکھ رہی ہو تو directory tree جزوی طور پر درست ہو سکتا ہے اور errors کا دوسرا، الجھن پیدا کرنے والا دور شروع ہو سکتا ہے۔
PUID اور PGID کیا درست نہیں کرتے
یہ وہ حصہ ہے جہاں ان لوگوں کو مسئلہ درپیش آتا ہے جنہوں نے باقی سب کچھ درست کیا ہو۔ linuxserver base image کا user setup script startup کے وقت تین paths پر chown چلاتا ہے: /app، /config اور /defaults۔ آپ کے media mounts اس فہرست میں شامل نہیں ہیں۔ /data، /downloads اور /tv application کو بغیر کسی تبدیلی کے دے دیے جاتے ہیں۔ اس لیے اگر ان mounts کے host side کی ownership ایسی ہو جس پر container user write نہ کر سکے، تو container بظاہر درست طور پر start ہوتا ہے، اپنے banner میں درست UID دکھاتا ہے، اور پھر پہلے import پر fail ہو جاتا ہے۔
یہی درست رویہ ہے۔ ہر container start پر بارہ terabyte کی media library پر recursive chown چلانا تباہ کن ہوگا۔ اس کا مطلب یہ ہے کہ media directories کی ذمہ داری آپ کی ہے، اور permissions کی اصل خرابی عموماً انہی mounts میں ہوتی ہے۔ اس قسم کی failure container کے healthy نظر آنے کے کئی گھنٹے بعد application log میں خاموشی سے ظاہر ہو سکتی ہے۔ اس لیے اپنے VPS پر ntfy، جو آپ کے phone پر alerts بھیجے کے ذریعے periodic write test منسلک کرنا ایک کم خرچ طریقہ ہے۔ اس سے آپ کو مسئلے کا بروقت علم ہو جاتا ہے، اس سے پہلے کہ ایک ہفتے کی missing episodes خود اس کی نشاندہی کریں۔
صارف کو کنٹرول کرنے کے 3 طریقے، اور ہر طریقہ کب استعمال کیا جائے
PUID اور PGID environment variables
یہ صرف ان images پر کام کرتا ہے جن کا entrypoint انہیں پڑھتا ہے۔ یہ طریقہ مقبول ہے، کیونکہ container ابتدا میں root کے طور پر start ہوتا ہے، اپنا setup مکمل کرتا ہے، /config کو درست کرتا ہے، اور پھر privileges کم کر دیتا ہے۔ Docker Mods اور custom init scripts بھی کام کرتے رہتے ہیں۔ اس کی قیمت یہ ہے کہ آپ platform feature کے بجائے ایک convention پر اعتماد کر رہے ہوتے ہیں، اور variable names مختلف projects میں standard نہیں ہوتے۔
Compose میں user: key
یہ Docker کا حقیقی feature ہے اور ہر image پر کام کرتا ہے، کیونکہ container runtime اسے image کے اپنے code کے چلنے سے پہلے apply کرتا ہے:
services:
sonarr:
image: lscr.io/linuxserver/sonarr:latest
user: "1000:1000"Process کبھی بھی root کے طور پر نہیں چلتا، ایک لمحے کے لیے بھی نہیں۔ یہ حقیقی security فائدہ ہے۔ لیکن entrypoint میں root privileges درکار کوئی بھی چیز ناکام ہو جاتی ہے۔ linuxserver images میں project اسے معقول کوشش کی بنیاد پر، اور صرف ان images کے لیے support کرتا ہے جنہیں اس نے test کیا ہو۔ اس کے مخصوص caveats یہ ہیں: PUID اور PGID کا کوئی اثر نہیں رہتا، Docker Mods نہیں چلیں گے، custom services نہیں چلیں گی، اور ہر mounted volume کی permissions کی ذمہ داری آپ کی ہو گی۔ ان کی documented pattern میں flag کے ساتھ writable /run استعمال کیا جاتا ہے:
user: 1000:1000
tmpfs:
- /run:uid=1000,gid=1000,exec
security_opt:
- no-new-privileges=trueایک ظاہری ضمنی اثر لوگوں کو حیران کرتا ہے۔ کوئی numeric user: جس کا container کے /etc/passwd میں matching entry نہ ہو، tools کے اندر whoami: cannot find name for user ID 1000 ظاہر کراتا ہے۔ ID valid رہتی ہے اور file access معمول کے مطابق کام کرتا ہے۔ صرف name lookup ناکام ہوتا ہے۔
Rootless Docker
Rootless Docker daemon کو خود آپ کے unprivileged user کے طور پر چلاتا ہے، اس لیے daemon اور containers host کے root privileges کے بغیر چلتے ہیں۔ اس سے ownership کا پورا حساب بدل جاتا ہے۔ Container UID 0، rootless Docker چلانے والے user کے host UID سے map ہوتا ہے، جبکہ container UID n، کسی بھی n کے لیے جو 1 یا اس سے زیادہ ہو، subuid + (n - 1) سے map ہوتا ہے؛ یہاں subuid اس range کی بنیاد ہے جو /etc/subuid میں آپ کے لیے مختص کی گئی ہے۔ Group IDs بھی /etc/subgid استعمال کرتے ہوئے اسی اصول کی پیروی کرتی ہیں۔ Docker وہاں کم از کم 65,536 subordinate IDs کی توقع کرتا ہے۔
اس mapping کو دوبارہ پڑھیں، کیونکہ یہ عام مشورے کو الٹ دیتی ہے۔ Rootless Docker کے تحت container جب عام طور پر root کے طور پر file بناتا ہے تو file کی ownership آپ کے نام پر ہوتی ہے۔ Container جب UID 1000 کے طور پر file بناتا ہے تو file عموماً کسی subordinate ID کے نام پر ہوتی ہے، مثلاً جب range 100000 سے شروع ہو تو 100999۔ آپ کے shell کی access permissions اور ACLs پر منحصر ہوتی ہے۔ File delete کرنا عموماً containing directory پر منحصر ہوتا ہے، اس لیے جس directory کا control آپ کے پاس ہو وہاں سے آپ یہ file delete کر سکتے ہیں۔ اس لیے rootful daemon پر درست PUID value یہاں غلط ہو گی۔ دونوں mechanisms مختلف layers پر ownership تبدیل کرتے ہیں، اور جانچ کے بغیر انہیں ایک ساتھ استعمال کرنے سے mounted data میں write کرنے کی صلاحیت ختم ہو سکتی ہے۔ اگر آپ rootless استعمال کریں تو library migrate کرنے سے پہلے اپنے server پر ایک لکھی ہوئی file کی ownership test کریں۔
ایک single VPS پر زیادہ تر self-hosted stacks کے لیے rootful daemon پر PUID اور PGID عملی انتخاب ہیں، کیونکہ images اسی مقصد کے لیے بنائی اور document کی گئی ہیں۔ user: اس وقت استعمال کریں جب image README میں لکھا ہو کہ image اس کے لیے tested ہے، یا جب آپ کوئی official upstream image چلا رہے ہوں جس میں PUID support موجود نہ ہو۔ ایک document workspace، جیسے ایک VPS پر self-hosted AFFiNE instance، دوسری صورت میں آتا ہے، کیونکہ اس کے کوئی بھی containers PUID نہیں پڑھتے، اور اس کی database directory اور uploaded files کی ownership runtime طے کرتا ہے، نہ کہ environment block میں موجود کوئی چیز۔ یہی بات ایک self-hosted Chatwoot support desk پر بھی لاگو ہوتی ہے، جہاں Rails container اور اس کا Sidekiq worker ایک ہی uploads directory میں لکھتے ہیں اور دونوں میں سے کوئی بھی PUID نہیں پڑھتا۔ اس لیے اس directory کی ownership اس user سے match ہونی چاہیے جس کے طور پر image پہلے ہی چلتی ہے۔ نئے stack کے لیے بھی یہ اصول نہیں بدلتا۔ اس لیے ٹیم کے ہر فرد کو اپنا sandboxed OneCLI agent دینا فی فرد workspace directories اور Postgres data directory کو اسی user کی ملکیت میں رکھتا ہے جس کے طور پر ہر image پہلے ہی چلتی ہے۔ یہ user: اور chown کا مسئلہ ہے، PUID کا نہیں۔ Codex، Claude Code اور Hermes کے سامنے ایک single self-hosted API رکھیں تو اس کا entrypoint کئی identities manage کرتا ہے: container کو root کے طور پر start ہونا چاہیے، console اور gateway کو unprivileged user کے طور پر چلنا چاہیے، اور ہر agent session کو اپنے user کے طور پر چلنا چاہیے۔ اس deployment میں user: شامل نہ کریں؛ اس کا entrypoint data volume کی ownership خود manage کرتا ہے۔
میڈیا stack کا معاملہ: containers کے درمیان ایک مشترک group
ایک Sonarr، Radarr اور download client پر مشتمل arr میڈیا stack وہ مقام ہے جہاں یہ صرف نظریہ نہیں رہتا۔ download client مکمل فائل کو /data/downloads میں لکھتا ہے۔ پھر Sonarr اس فائل کو hardlink کرتا ہے یا /data/media میں منتقل کرتا ہے۔ hardlink کے لیے دونوں containers کو اسی tree تک write access درکار ہوتی ہے۔ اگر download client 1000 کے طور پر اور Sonarr 1001 کے طور پر چل رہا ہو، اور shared group write permissions موجود نہ ہوں، تو ان میں سے ایک ایسی فائلوں کا مالک بن جاتا ہے جنہیں دوسرا صرف پڑھ سکتا ہے۔
اس کا حل ایک shared group ہے جسے stack کا ہر container اپنے PGID کے طور پر استعمال کرے:
sudo groupadd -g 13000 media
sudo usermod -aG media deploy
sudo chown -R deploy:media /srv/media
sudo find /srv/media -type d -exec chmod 2775 {} +
sudo find /srv/media -type f -exec chmod 0664 {} +2775 میں شروع کا 2 setgid bit ہے۔ کسی directory پر اس کا مطلب ہے کہ اس کے اندر بننے والی ہر نئی file اور subdirectory creator کے اپنے primary group کے بجائے group media inherit کرے گی۔ اس طرح نئی downloads کے بعد آپ کو chown دوبارہ چلانے کی ضرورت نہیں رہتی۔ اپنی access کی جانچ سے پہلے log out کرکے دوبارہ log in کریں، یا newgrp media چلائیں۔ usermod -aG سے شامل کیا گیا group پہلے سے کھلے shell session میں ظاہر نہیں ہوتا۔
container کے اندر groupmod -o -g 13000 abc، abc group کا نمبر بدل کر 13000 کر دیتا ہے۔ اس طرح abc اسی GID کے ساتھ لکھتا ہے جو آپ کے host کے media group کا ہے۔ اس tree تک رسائی رکھنے والا ہر linuxserver container اپنا PUID برقرار رکھتا ہے اور وہی PGID share کرتا ہے۔ اس میں chain کے بعد والے وہ containers بھی شامل ہیں جو مکمل library کو صرف پڑھتے ہیں، جیسے خود Jellyfin۔ Halcyon جیسا front end، جو اس library کو چلنے پھرنے کے قابل 90s ویڈیو اسٹور کے طور پر پیش کرتا ہے، HALCYON_JELLYFIN_URL استعمال کرتے ہوئے HTTP کے ذریعے Jellyfin سے connect ہوتا ہے۔ اس کی standard deployment کو نہ shared media PGID درکار ہوتا ہے اور نہ media-directory mount۔
اب stack کے ہر linuxserver container میں UMASK=002 مقرر کریں۔ لوگ اکثر یہی قدم چھوڑ دیتے ہیں۔ اگر یہ مقرر نہ ہو تو application اپنا inherited umask برقرار رکھتی ہے، جب تک کوئی اور چیز اسے تبدیل نہ کرے۔ image READMEs میں دکھائی جانے والی example value UMASK=022 ہے۔ effective umask 022 ہونے پر، اگر application نئی file کے لیے 0666 مانگے اور default ACL موجود نہ ہو، تو اسے 0644 ملتا ہے۔ group کے باقی ارکان اسے پڑھ سکتے ہیں، مگر تبدیل نہیں کر سکتے۔ اس سے آپ کی بنائی ہوئی sharing کا زیادہ تر فائدہ ختم ہو جاتا ہے۔ 002 اور default ACL کے بغیر، جب application files کے لیے معمول کا 0666 اور directories کے لیے 0777 مانگتی ہے، تو اسے 0664 files اور setgid tree کے اندر 2775 directories ملتی ہیں، اور group میں write access رہتی ہے۔ umask صرف bits ہٹاتا ہے۔ اس لیے 0600 مانگنے والی application کو 0600 ہی ملتا ہے۔ default ACL رکھنے والی directory umask کو مکمل طور پر نظرانداز کرتی ہے۔ variable کو PUID اور PGID کے ساتھ شامل کریں:
services:
sonarr:
image: lscr.io/linuxserver/sonarr:latest
container_name: sonarr
environment:
- PUID=${PUID}
- PGID=${PGID}
- UMASK=002
- TZ=Etc/UTC
volumes:
- /srv/appdata/sonarr:/config
- /srv/media:/data
restart: unless-stoppedیہ دونوں values Compose file کے ساتھ موجود .env file میں ہونی چاہییں، تاکہ پورا stack ایک ہی definition استعمال کرے:
PUID=1000
PGID=13000Compose اس file کو ${PUID} طرز کی substitution کے لیے خودکار طور پر پڑھتا ہے۔ یہی mechanism credentials کے لیے بھی استعمال ہوتا ہے۔ values کو docker-compose.yml سے باہر رکھ کر .env file میں رکھنے کے اصول یہاں بھی لاگو ہوتے ہیں۔ فرق صرف یہ ہے کہ یہ دونوں numbers secret نہیں ہیں۔
configuration پر بھروسا کرنے کے بجائے مکمل end-to-end تصدیق کریں۔ application user کے طور پر ایک نئی file لکھیں، مقررہ umask لاگو کریں، اور اسے host سے پڑھیں۔ ایسا test filename استعمال کریں جو پہلے سے موجود نہ ہو:
docker exec --user abc sonarr sh -c 'umask "$UMASK" && touch /data/downloads/permtest'
ls -ln /srv/media/downloads/permtestدرست نتیجے میں owner کے طور پر آپ کا PUID، group کے طور پر 13000، اور mode کے طور پر -rw-rw-r-- نظر آئے گا۔ اگر group 1000 دکھائے تو ls -ldn /srv/media/downloads چلائیں۔ اس کی دو وجوہات ہو سکتی ہیں: directory میں setgid bit، یعنی drwxrwsr-x کا s، موجود نہیں؛ یا directory خود group 1000 کی ملکیت ہے، media کی نہیں۔ اوپر دیے گئے chown اور chmod 2775 commands دونوں مسائل درست کرتے ہیں۔ اگر mode -rw-r--r-- دکھائے تو container کی UMASK value اور directory کی default ACL چیک کریں۔ اگر environment پرانی ہو تو container دوبارہ بنائیں۔ یہ test configured mask کے ساتھ abc کے طور پر creation کو جانچتا ہے۔ Application کا اپنا creation mode اور effective umask اب بھی اس کی files کا تعین کرتے ہیں۔ مکمل ہونے پر rm /srv/media/downloads/permtest سے test file حذف کریں۔
کون سی images کون سا variable استعمال کرتی ہیں
linuxserver.io images PUID، PGID اور UMASK استعمال کرتی ہیں۔ Paperless-ngx میں اسی تصور کے لیے مختلف نام استعمال ہوتے ہیں: USERMAP_UID اور USERMAP_GID، اور دونوں کی default value 1000 ہے۔ اس کی documentation میں بتایا گیا ہے کہ انہیں id -u اور id -g سے پڑھا جائے۔ Photo servers میں بھی یہی فرق نظر آتا ہے: PhotoPrism کی اپنی PHOTOPRISM_UID اور PHOTOPRISM_GID کی جوڑی ہے، جبکہ Immich میں اس کا کوئی equivalent نہیں ہوتا اور container user کے لیے Docker کی user: key استعمال ہوتی ہے۔ اس لیے PhotoPrism اور Immich میں انتخاب یہ بھی طے کرتا ہے کہ سرور کی سب سے بڑی library کے لیے آپ کو ان میں سے کون سا mechanism maintain کرنا ہوگا۔ بہت سی official upstream images، جن میں عام database اور web server images شامل ہیں، ایک fixed built-in user فراہم کرتی ہیں اور توقع کرتی ہیں کہ آپ user: استعمال کریں یا اسے ویسے ہی رہنے دیں۔ چھوٹی single-app deployments میں بھی یہی سوال پیدا ہوتا ہے۔ اس لیے جب آپ self-hosted openGym workout tracker قائم کریں تو bind mount لگانے سے پہلے یہ ضرور دیکھیں کہ اس کا container حقیقت میں کس user کے طور پر چلتا ہے۔ اس کی database رکھنے والی directory اسی انتخاب کے مطابق ownership حاصل کرے گی، چاہے آپ PUID set کریں یا نہ کریں۔ Remote access relay بھی اسی category میں آتا ہے۔ لہٰذا جب آپ اپنا RustDesk relay server چلائیں تو hbbs پہلی بار start ہونے پر جو Ed25519 key pair لکھتا ہے، وہ آپ کے bind mount میں اسی user کی ownership کے ساتھ آئے گا جس user پر وہ image ختم ہوئی تھی۔ آپ بعد میں host side chown سے ownership درست کر سکتے ہیں، یا user: key کے ذریعے ابتدا ہی میں identity منتخب کر سکتے ہیں، کیونکہ یہ image خود کوئی user set نہیں کرتی۔ شرط یہ ہے کہ mounted directory آپ کے منتخب کردہ ID کے لیے writable ہو۔ بعد میں شامل کیے جانے والے infrastructure پر بھی یہی اصول لاگو ہوتا ہے۔ اس لیے اپنی apps کے سامنے Authentik رکھ کر single login قائم کرنے کا مطلب ہے کہ آپ official authentik اور Postgres images چلائیں گے، جو PUID بالکل نہیں پڑھتیں۔ ان کے volumes کی ownership ان users سے آتی ہے جن کے طور پر ان کے processes چلتے ہیں، اور اس setup سے بھی جو ان کے entrypoints انجام دیتے ہیں۔ Authentik نے release 2025.10 میں اپنی Redis dependency ختم کر دی ہے۔
اس لیے projects کے درمیان environment block copy کرنے سے پہلے ہر image کی README دیکھیں۔ Docker آپ کی set کی ہوئی ہر environment variable ہر container میں پہنچاتا ہے، خواہ container کے اندر کوئی چیز اسے پڑھتی ہو یا نہیں۔ اگر PUID کو کوئی چیز استعمال نہ کرے تو کوئی error، warning یا اثر پیدا نہیں ہوتا۔ Container اس user کے طور پر start ہوتا ہے جسے Docker کی user: setting یا Dockerfile منتخب کرتی ہے۔ اس کے بعد entrypoint application start کرنے سے پہلے privileges کم کر سکتا ہے۔ Box میں کوئی نئی چیز شامل کرنے سے پہلے یہ معلومات پڑھ لیں۔ اس میں self-hosted open-kritt security scanning stack بھی شامل ہے، جہاں Compose file بتاتی ہے کہ images PUID کو support کرتی ہیں یا mounted directories کی ownership خود images کے ذریعے fixed ہے۔
FAQ
میری Docker فائلوں کی ملکیت 911:911 کیوں ہے؟
911، abc user کا UID اور GID ہے، جو linuxserver.io images میں شامل ہوتا ہے۔ اگر یہ ملکیت نظر آ رہی ہے تو یہ built-in defaults سے مطابقت رکھتی ہے، لیکن container کے PUID اور PGID تبدیل کرنے کے بعد بھی فائلیں یہ ملکیت برقرار رکھ سکتی ہیں۔ جب host پر ان IDs سے مطابقت رکھنے والا کوئی account نہ ہو تو ls -l خام numbers دکھاتا ہے، کیونکہ دکھانے کے لیے کوئی نام موجود نہیں ہوتا۔ PUID اور PGID کو id کے output پر set کریں، docker compose up -d کے ساتھ container دوبارہ بنائیں، پھر متاثرہ directory میں موجود فائلوں کی ملکیت sudo chown -R 1000:1000 کے ذریعے درست کریں۔
کیا PUID اور PGID ہر Docker image پر کام کرتے ہیں؟
نہیں۔ یہ Docker کی feature نہیں ہیں، اور Docker انہیں کبھی read نہیں کرتا۔ یہ صرف ان images پر کام کرتے ہیں جن کا اپنا entrypoint انہیں read کرکے application شروع کرنے سے پہلے usermod اور groupmod چلاتا ہے۔ اس میں linuxserver.io family اور چند وہ projects شامل ہیں جنہوں نے یہی pattern اپنایا ہے۔ دوسرے projects دوسرے نام استعمال کرتے ہیں، مثلاً paperless-ngx میں USERMAP_UID اور USERMAP_GID۔ جو image ان میں سے کسی variable کو read نہ کرے، اس میں variables قبول تو ہو جاتے ہیں لیکن کسی warning کے بغیر نظرانداز کر دیے جاتے ہیں۔
کیا Docker Compose میں PUID اور PGID استعمال کروں یا user: key؟
جب image انہیں support کرتی ہو تو PUID اور PGID استعمال کریں، کیونکہ entrypoint اتنی دیر تک root کے طور پر چلتا رہتا ہے کہ /config درست کر سکے اور اپنی services صحیح طور پر شروع کر سکے۔ user: اس وقت استعمال کریں جب image منتخب user کے لیے اس کی support document کرتی ہو؛ صرف PUID کی support نہ ہونا اس بات کا مطلب نہیں کہ اس کا entrypoint root کے بغیر کام کرے گا۔ linuxserver image میں user: set کرنے سے PUID اور PGID غیر مؤثر ہو جاتے ہیں، Docker Mods اور custom services چلنا بند ہو جاتے ہیں، اور ہر mounted volume کی permissions آپ کی ذمہ داری بن جاتی ہیں۔
Sonarr کے پاس درست PUID ہے، لیکن پھر بھی فائلیں منتقل نہیں کر سکتا۔ خرابی کہاں ہے؟
تین چیزیں ترتیب سے check کریں۔ پہلی چیز خود media mount ہے: base image کا user setup script /app، /config اور /defaults پر chown چلاتا ہے، اس لیے /data یا /downloads host پر موجود ملکیت برقرار رکھتا ہے۔ دوسری چیز shared group ہے: media tree تک رسائی رکھنے والے containers کو ایک ہی PGID دیں اور group write permissions فراہم کریں۔ تیسری چیز umask ہے: اگر application 0666 کی درخواست کرے اور کوئی default ACL لاگو نہ ہو، تو 022 کی effective mask سے 0644 files بنتی ہیں۔ ایسی صورت میں group کے دوسرے containers انہیں read کر سکتے ہیں، لیکن modify نہیں کر سکتے۔ UMASK کو unset چھوڑنے سے کسی خاص mask یا file mode کی ضمانت نہیں ملتی۔ UMASK=002 set کریں اور chmod 2775 کے ذریعے directories پر setgid bit لگائیں، تاکہ نئی فائلیں group inherit کریں۔ اگر application 0600 کی درخواست کرے تو پھر بھی private files بنتی ہیں، اور default ACL اس بات کو تبدیل کر دیتا ہے کہ creation permissions کس طرح assign ہوں گی۔