آٹو ڈیپلائی

آٹو ڈیپلائی کیسے کام کرتا ہے

جب بھی GitHub اس برانچ کے لیے push event بھیجتا ہے جسے ایپ ٹریک کرتی ہے، آٹو ڈیپلائی اس GitHub ایپ کو دوبارہ تعینات کرتا ہے۔ Server Compass آپ کے سرور پر ایک ہمیشہ فعال gateway اور ایک نجی deployment worker انسٹال کرتا ہے، ریپوزیٹری کا webhook بناتا ہے، GitHub کی signed test delivery کی تصدیق کرتا ہے، اور تعیناتی کے لیے بالکل وہی commit قطار میں لگا دیتا ہے۔

سیٹ اپ کے بعد Server Compass ڈیسک ٹاپ ایپ کو کھلا رکھنے کی ضرورت نہیں۔ سرور کی طرف کا runtime، Docker کے ساتھ دوبارہ شروع ہوتا ہے اور webhook وصول کرتا رہتا ہے، ایپ build کرتا رہتا ہے، اور تعیناتی کی تاریخ ریکارڈ کرتا رہتا ہے۔ آپ کا SSH پورٹ نجی رہ سکتا ہے؛ صرف webhook کا hostname ہی GitHub سے HTTPS کے ذریعے قابلِ رسائی ہونا چاہیے۔

تقاضے

شروع کرنے سے پہلے، تصدیق کریں کہ آپ کے پاس یہ موجود ہیں:

• ایک Docker ایپ جو پہلے ہی کسی GitHub ریپوزیٹری سے تعینات ہو چکی ہو
• build مقام کے طور پر Build on VPS منتخب ہو؛ GitHub Actions builds کو webhook Auto Deploy v1 سپورٹ نہیں کرتا
• ایپ کی Server Compass ڈائریکٹری کے اندر ایک منظم Git checkout
• ایک منسلک GitHub اکاؤنٹ جسے ریپوزیٹری webhooks بنانے کی اجازت ہو
• سرور پر Docker Engine اور Docker Compose
• ایک مخصوص عوامی HTTPS hostname جیسے deploy.example.com
• اس hostname سے webhook gateway تک ایک route

آٹو ڈیپلائی تعینات شدہ ایپ پر محفوظ برانچ کی پیروی کرتا ہے۔ اس بالکل مخصوص برانچ پر ہر push، GitHub event میں شامل commit کو قطار میں لگا دیتا ہے؛ دیگر برانچوں پر push نظر انداز کر دیے جاتے ہیں۔

ایپ سیٹ اپ کرنا

1. Server Compass میں، ریپوزیٹری کو ایک GitHub ایپ کے طور پر تعینات کریں۔
2. تعیناتی کے دوران Build on VPS منتخب کریں۔
3. تعینات شدہ ایپ کھولیں اور Deployments پر جائیں۔
4. آٹو ڈیپلائی کارڈ تلاش کریں اور Set up Auto Deploy پر کلک کریں۔
5. ایک عوامی webhook hostname درج کریں۔ صرف hostname یا HTTPS origin استعمال کریں، مثلاً deploy.example.com یا https://deploy.example.com۔ کوئی path، query string یا حسبِ ضرورت پورٹ شامل نہ کریں۔

hostname، GitHub کے لیے عوامی داخلی راستہ ہے۔ صرف ایک ڈومین کافی نہیں: DNS، TLS، firewall یا NAT قواعد، اور آپ کا proxy یا tunnel، سرور پر gateway تک ایک مکمل route بنانا ضروری ہے۔

منتخب کریں کہ GitHub سرور تک کیسے پہنچے

تینوں route اختیارات ایک ہی signed webhook اور نجی deployment worker استعمال کرتے ہیں۔ صرف عوامی route مختلف ہے۔

Server Compass-managed Traefik

جب Server Compass-managed Traefik پہلے ہی سرور پر عوامی reverse proxy ہو تو اسے استعمال کریں۔ hostname کا DNS record سرور کی طرف اشارہ کریں اور یقینی بنائیں کہ inbound پورٹ 80 اور 443 اس تک پہنچتے ہیں۔ Server Compass، webhook gateway کو موجودہ traefik-public Docker نیٹ ورک سے منسلک کرتا ہے اور HTTPS ہوسٹ route کنفیگر کرتا ہے۔

عوامی VPS کے لیے یہ عام طور پر سب سے آسان اختیار ہے۔ یہ کسی LAN سرور کے لیے بھی کام کر سکتا ہے جب router پورٹ 80 اور 443 کو اس سرور کی طرف forward کرے اور hostname، router کے عوامی IP پر resolve ہو۔

Existing reverse proxy

جب Nginx، Caddy، Traefik، HAProxy یا کوئی اور proxy پہلے ہی hostname سنبھال رہا ہو تو اسے استعمال کریں۔ تیار کردہ loopback target حاصل کرنے کے لیے Check server پر کلک کریں، پھر webhook hostname کو دکھائے گئے پتے کی طرف route کریں، مثلاً http://127.0.0.1:42315۔

Proxy کو خام request body اور GitHub webhook headers محفوظ رکھنے چاہییں تاکہ gateway، HMAC signature کی تصدیق کر سکے۔ اس route کے سامنے login middleware، Cloudflare Access یا کوئی اور تعامل والا authentication صفحہ نہ رکھیں۔

اگر proxy، Docker میں چل رہا ہے، تو یاد رکھیں کہ proxy container کے اندر 127.0.0.1 اسی container کی طرف اشارہ کرتا ہے۔ اس کے بجائے host networking، host-gateway پتہ، یا کوئی مناسب مشترکہ Docker نیٹ ورک استعمال کریں۔

Stable tunnel

اسے کسی LAN سرور، نجی VPS، CGNAT کنکشن، یا کسی بھی ایسے سرور کے لیے استعمال کریں جہاں آپ inbound پورٹ نہیں کھولنا چاہتے۔ ایک مستقل named Cloudflare Tunnel یا اس کے مساوی tunnel بنائیں، اس کا connector سرور پر چلائیں، اور عوامی hostname کو Check server کے دکھائے گئے loopback target سے map کریں، جیسے http://127.0.0.1:42315۔

Tunnel کو مستحکم ہونا چاہیے اور reboot کے بعد خودکار شروع ہونا چاہیے۔ عارضی Quick Tunnel یا ایسا ngrok URL جو restart پر بدل جائے، موزوں نہیں کیونکہ GitHub، webhook کا URL محفوظ کر لیتا ہے۔ اگر connector، Docker میں چل رہا ہے، تو اسے host networking یا کوئی اور route دیں جو واقعی host پر gateway تک پہنچ سکے۔

سرور چیک کریں اور فعال کریں

1. Check server پر کلک کریں۔
2. تصدیق کریں کہ Docker Engine، Docker Compose، اور تجویز کردہ gateway پورٹ readiness check پاس کرتے ہیں۔
3. اگر آپ نے managed Traefik منتخب کیا ہے، تو تصدیق کریں کہ traefik-public نیٹ ورک بھی پاس کرتا ہے۔
4. اگر آپ نے موجودہ proxy یا stable tunnel منتخب کیا ہے، تو نتیجے میں دکھائے گئے بالکل درست loopback پورٹ تک بیرونی route مکمل کریں۔
5. Activate Auto Deploy پر کلک کریں۔

Server Compass، gateway اور worker انسٹال کرتا ہے، ایک نجی webhook URL بناتا ہے، signing secret کو سرور پر محفوظ کرتا ہے، GitHub میں webhook بناتا ہے، ایک GitHub ping بھیجتا ہے، اور ایک کامیاب signed delivery کا انتظار کرتا ہے۔ حالت Installed، Routed، Hooked، Verified، اور Active سے گزرتی ہے۔

اگر سیٹ اپ Awaiting route پر رک جائے، تو runtime پہلے ہی انسٹال ہو چکا ہے مگر GitHub ابھی اس تک نہیں پہنچ سکتا۔ DNS، TLS، firewall/NAT، proxy، یا tunnel route مکمل یا درست کریں، پھر Continue setup پر کلک کریں۔ آپ کو ایپ دوبارہ انسٹال کرنے کی ضرورت نہیں۔

آٹو ڈیپلائی کی تصدیق کریں

پہلے تصدیق کریں کہ عوامی health endpoint، Server Compass gateway تک پہنچتا ہے:

curl -fsS https://deploy.example.com/healthz

پھر مکمل تعیناتی flow کی تصدیق کریں:

1. GitHub میں، ریپوزیٹری کھولیں اور Settings > Webhooks پر جائیں۔
2. Server Compass کے بنائے گئے webhook کو کھولیں اور تصدیق کریں کہ اس کی تازہ ترین delivery نے 2xx جواب دیا۔
3. ٹریک کردہ برانچ پر ایک چھوٹا commit push کریں۔
4. Server Compass میں، ایپ کی تعیناتی تاریخ کھولیں اور تصدیق کریں کہ webhook job نے push کیے گئے commit کو استعمال کیا۔
5. تصدیق کریں کہ تعینات شدہ ایپلیکیشن میں وہ تبدیلی موجود ہے۔

آخری ٹیسٹ کے لیے، Server Compass کو مکمل طور پر بند کریں، ٹریک کردہ برانچ پر ایک اور commit push کریں، اور ایپلیکیشن کی دوبارہ تصدیق کریں۔ تعیناتی پھر بھی مکمل ہونی چاہیے کیونکہ gateway، قطار، اور worker سرور پر چلتے ہیں۔

فعال webhook کا نظم کریں

آٹو ڈیپلائی کارڈ یہ اعمال فراہم کرتا ہے:

• Test webhook ایک اور GitHub test delivery بھیجتا ہے اور اس کی حالت تازہ کرتا ہے۔
• Rotate secret، سرور اور GitHub webhook دونوں پر signing secret تبدیل کر دیتا ہے۔
• Pause، target اور تاریخ برقرار رکھتا ہے مگر خودکار تعیناتیاں روک دیتا ہے؛ Resume انہیں دوبارہ فعال کر دیتا ہے۔
• Remove، GitHub webhook اور اس کی remote target policy حذف کر دیتا ہے، جبکہ تعیناتی کی تاریخ برقرار رکھتا ہے۔

ٹریک کردہ ریپوزیٹری یا برانچ تبدیل کرنے کے لیے، پہلے آٹو ڈیپلائی کو Remove کریں، نئی ریپوزیٹری یا برانچ کے ساتھ ایپ کو اپ ڈیٹ اور دوبارہ تعینات کریں، پھر آٹو ڈیپلائی دوبارہ سیٹ اپ کریں۔

مسائل کا حل اور سیکیورٹی

• Health endpoint ناکام ہو یا 502/404 لوٹائے: DNS اور TLS کی تصدیق کریں، یقینی بنائیں کہ proxy یا tunnel موجودہ loopback پورٹ کی طرف اشارہ کرتا ہے، اور یقینی بنائیں کہ gateway container چل رہا ہے۔
• GitHub delivery، 2xx نہ ہو: webhook کی حالیہ delivery کا جائزہ لیں، تصدیق کریں کہ کوئی authentication layer GitHub کو نہیں روک رہی، اور یقینی بنائیں کہ proxy نے خام body تبدیل نہیں کی یا GitHub headers نہیں ہٹائے۔
• Push سے تعیناتی نہ ہو: تصدیق کریں کہ آٹو ڈیپلائی، Paused نہیں بلکہ Active ہے، اور push بالکل درست ٹریک کردہ برانچ پر کیا گیا تھا۔
• Tunnel، reboot تک کام کرتا رہا: named tunnel connector کو system service یا دوبارہ شروع ہونے والے container کے طور پر کنفیگر کریں۔ عارضی URL استعمال نہ کریں۔
• ڈیسک ٹاپ بند ہے اور تعیناتی ناکام ہو رہی ہے: جانچیں کہ سرور آن لائن ہے اور Server Compass کے gateway اور worker containers چل رہے ہیں۔

webhook URL میں ایک نجی route token ہوتا ہے اور اسے شائع نہیں کرنا چاہیے۔ GitHub deliveries کی تصدیق ایک HMAC signing secret سے ہوتی ہے جو سرور پر تیار اور محفوظ کیا جاتا ہے اور UI میں کبھی ظاہر نہیں کیا جاتا۔ آپ کو SSH، Docker socket، یا نجی worker کو انٹرنیٹ پر بے نقاب کرنے کی ضرورت نہیں۔