SSD Nodes Learn Hosting plans →
تعلیمی Matt Connorتحریر: Matt Connor · اپ ڈیٹ شدہ 2026-10-24

Docker میں wg-easy سے WireGuard ویب UI چلائیں

Docker Compose میں wg-easy چلانے کا درست طریقہ: ports، NET_ADMIN، ضروری sysctls، version 15 کی settings، اور فون کے لیے QR code onboarding۔

آپ کیا بنا رہے ہیں

wg-easy ایک web interface کے ساتھ WireGuard ہے جو ایک Docker container کے طور پر چلتا ہے۔ یہ آپ کے لیے WireGuard interface manage کرتا ہے اور clients بنانے کے لیے browser UI فراہم کرتا ہے۔ آپ کے بنائے ہوئے ہر client کو ایک config file اور QR code ملتا ہے، اس لیے فون کو VPN سے جوڑنے کے لیے اس کا camera screen کی طرف کرنا کافی ہوتا ہے۔

Tunnel خود معمول کا WireGuard ہے۔ Kernel module packets منتقل کرتا ہے، اس لیے throughput ہاتھ سے لکھی گئی setup کے برابر رہتا ہے۔ آپ کو client lifecycle کا انتظام ملتا ہے: SSH کے ذریعے config file میں ترمیم کیے بغیر peers شامل کرنا، غیر فعال کرنا اور حذف کرنا۔ اس کے بدلے config پر براہ راست control محدود ہو جاتا ہے۔ اسی موضوع پر VPS پر manual WireGuard setup میں بات کی گئی ہے۔

آپ کو ایسا Linux host درکار ہے جسے آپ manage کر سکیں، مثلاً KVM VPS، اور اس کے ساتھ public IP address یا ایسا domain name جو اس کی طرف point کرتا ہو، x86_64 یا arm64 CPU، Compose plugin کے ساتھ Docker Engine، اور root access۔ ایسی container virtualisation جو host kernel شیئر کرتی ہے، مثلاً OpenVZ یا LXC، عموماً WireGuard module load نہیں کر سکتی۔ اس صورت میں container interface کو فعال کرنے میں ناکام ہو جائے گا۔

ورژن 15 نے settings کو environment سے منتقل کر دیا

آپ کو ملنے والی زیادہ تر guides wg-easy 14 کے لیے لکھی گئی تھیں۔ ان میں آپ WG_HOST میں اپنے server کا address اور PASSWORD_HASH میں admin password کا bcrypt hash بطور environment variables set کرتے تھے۔ ورژن 15 مکمل طور پر دوبارہ لکھا گیا ہے۔ سرکاری migration notes واضح طور پر بتاتی ہیں کہ v15، v14 والے environment variables استعمال نہیں کرتا، اور ان میں سے زیادہ تر settings web UI کے admin panel میں منتقل کر دی گئی ہیں۔

اس لیے WG_HOST اور PASSWORD_HASH اب کوئی اثر نہیں ڈالتے۔ اگر آپ پرانی compose file copy کرتے ہیں تو container start ہو جاتا ہے، ان lines کو نظرانداز کرتا ہے، اور پھر browser میں admin account بنانے کو کہتا ہے۔ یہ bug نہیں ہے۔ یہی نیا setup flow ہے۔

October 2026 تک pin کرنے کے لیے major tag 15 ہے۔ latest استعمال کرنے کے بجائے major version pin کریں، کیونکہ major upgrade on-disk config format تبدیل کرتا ہے اور صاف طریقے سے rollback نہیں ہوتا۔ ورژن 15 پر منتقلی کے دوران v14 کی JSON file کو SQLite database سے بدل دیا گیا۔

Compose فائل

Stack کے لیے ایک directory بنائیں اور اس میں official Compose فائل لکھیں۔ یہ upstream فائل ہے، جس میں commented-out اختیاری lines شامل نہیں کی گئی ہیں۔

sudo mkdir -p /etc/docker/containers/wg-easy
sudo curl -o /etc/docker/containers/wg-easy/docker-compose.yml \
  https://raw.githubusercontent.com/wg-easy/wg-easy/master/docker-compose.yml

اس کے contents اس طرح نظر آتے ہیں:

volumes:
  etc_wireguard:

services:
  wg-easy:
    image: ghcr.io/wg-easy/wg-easy:15
    container_name: wg-easy
    networks:
      wg:
        ipv4_address: 10.42.42.42
        ipv6_address: fdcc:ad94:bacf:61a3::2a
    volumes:
      - etc_wireguard:/etc/wireguard
      - /lib/modules:/lib/modules:ro
    ports:
      - "51820:51820/udp"
      - "51821:51821/tcp"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1

networks:
  wg:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 10.42.42.0/24
        - subnet: fdcc:ad94:bacf:61a3::/64

etc_wireguard ایک named volume ہے جس میں server key اور آپ کے بنائے ہوئے تمام clients محفوظ ہوتے ہیں۔ یہ ڈیٹا SQLite database wg-easy.db میں stored ہوتا ہے۔ اس volume کا backup لیں، ورنہ rebuild کے دوران آپ کے تمام peers ضائع ہو جائیں گے۔ اگر آپ یہ files host filesystem پر دیکھنا چاہتے ہیں تو اسے bind mount سے تبدیل کریں۔ ایسا کرنے سے پہلے bind mounts اور named volumes کے درمیان فرق پڑھ لیں، کیونکہ دونوں میں permissions کا طریقہ مختلف ہوتا ہے۔

اس کے لیے NET_ADMIN، SYS_MODULE اور sysctls درکار کیوں ہیں

کسی container کو بطور default network stack میں تبدیلی کرنے کی اجازت نہیں ہوتی، اور ان میں سے ہر لائن ایک مخصوص رکاوٹ دور کرتی ہے۔

NET_ADMIN، container کو wg0 interface بنانے، اسے address دینے اور routes لکھنے کی اجازت دیتا ہے۔ اس کے بغیر container شروع ہونے کے بعد interface فعال کرتے وقت بند ہو جاتا ہے، کیونکہ ip link add wg0 type wireguard، Operation not permitted واپس کرتا ہے۔

SYS_MODULE اور read-only /lib/modules mount، container کو WireGuard kernel module load کرنے دیتے ہیں، اگر host نے اسے پہلے سے load نہ کیا ہو۔ یہ module image کے اندر نہیں بلکہ host kernel میں موجود ہوتا ہے، اسی لیے host directory کو container میں قابل رسائی بنانا ضروری ہے۔ جدید kernel میں یہ module عموماً built in ہوتا ہے، اور آپ host پر sudo modprobe wireguard && echo ok سے اس کی تصدیق کر سکتے ہیں۔

net.ipv4.ip_forward=1، kernel کو ایسے packets forward کرنے کی ہدایت دیتا ہے جو خود box کے لیے addressed نہ ہوں۔ اس کے بغیر client connect ہو جاتا ہے، handshake کامیاب ہو جاتا ہے، لیکن internet کے لیے ہر packet drop ہو جاتا ہے۔ نتیجتاً ping 1.1.1.1 timeout ہو جاتا ہے، حالانکہ VPN connected دکھائی دیتا ہے۔

net.ipv4.conf.all.src_valid_mark=1 وہ setting ہے جو لوگوں کو عموماً حیران کرتی ہے۔ WireGuard اپنے outgoing packets کو mark کرتا ہے تاکہ وہ دوبارہ tunnel میں route نہ ہوں۔ Strict reverse path filtering ایسے packet کو دیکھ کر drop کر دیتی ہے جس کا source address متوقع route سے match نہیں کرتا۔ یہ sysctl kernel کو marked packets قبول کرنے کی ہدایت دیتا ہے، اور اسی سے full tunnel خود کو ناکام ہونے سے بچاتا ہے۔

اسے شروع کریں اور administrator account بنائیں

cd /etc/docker/containers/wg-easy
sudo docker compose up -d
sudo docker compose logs -f

docker compose up اور docker compose down استعمال کریں، start اور stop نہیں۔ start صرف پہلے سے موجود containers کو restart کرتا ہے، اس لیے compose file میں کی گئی کوئی بھی تبدیلی، بشمول network اور sysctl settings، لاگو نہیں ہوتی، جبکہ up تبدیل شدہ تمام چیزوں کو دوبارہ بناتا ہے۔ اگر آپ reboot کے بعد stack دوبارہ بحال کرنا چاہتے ہیں تو restart: unless-stopped اسے پہلے ہی handle کرتا ہے، اور compose services کے boot behaviour میں بتایا گیا ہے کہ یہ policy کیا ضمانت دیتی ہے اور کیا نہیں دیتی۔

web UI TCP 51821 پر listening کرتا ہے۔ پہلی بار کھولنے پر یہ setup page دکھاتا ہے، جہاں آپ administrator account بناتے ہیں اور host address کی تصدیق کرتے ہیں جس کے ذریعے clients server تک پہنچیں گے۔ یہ host address ہر client config کی Endpoint line میں شامل ہوتا ہے، اس لیے یہ VPS کا public IP یا DNS name ہونا چاہیے۔ اگر یہ غلط ہو تو phone کو دیا گیا QR code ایسے address کی طرف اشارہ کرے گا جہاں رسائی ممکن نہیں، اور handshake کبھی مکمل نہیں ہوگا۔

اس port کے بارے میں ایک اور بات: wg-easy خود TLS فراہم نہیں کرتا اور plain HTTP کو مسترد بھی نہیں کرتا۔ http:// کے ذریعے UI پھر بھی load ہوتا ہے اور warning banner دکھاتا ہے۔ default تبدیلی session cookie میں ہوتی ہے، جس میں Secure flag شامل ہوتا ہے۔ اس لیے public address پر plain HTTP کے ذریعے UI کھولنے والا browser cookie discard کر دیتا ہے اور login برقرار نہیں رہتا۔ INSECURE=true یہ flag ہٹا دیتا ہے اور کوئی دوسرا کام نہیں کرتا۔ اگر سامنے ایسا reverse proxy رکھا جائے جو TLS terminate کرے، حتیٰ کہ self-signed certificate کے ساتھ بھی، تو wg-easy میں کسی تبدیلی کی ضرورت نہیں ہوتی۔

انٹرفیس پورٹ کو انٹرنیٹ پر شائع نہ کریں

Compose file، 51821 کو ہر interface پر publish کرتی ہے۔ یہ اس مشین کا login page ہے جو آپ کے network traffic کو route کر سکتی ہے، اس لیے اسے پوری دنیا کے لیے کھلا نہیں ہونا چاہیے۔ Docker میں port publish کرنے سے rules، DOCKER chain میں لکھی جاتی ہیں۔ اس chain کا جائزہ ufw سے پہلے لیا جاتا ہے، اس لیے ufw کی deny rule اس port کو بند نہیں کرتی۔ اس مسئلے کو الگ سے سمجھنا ضروری ہے، اور Docker کے published ports ufw کو کیوں نظرانداز کرتے ہیں میں اس کی مکمل وضاحت موجود ہے۔

سادہ حل یہ ہے کہ UI کو loopback سے bind کریں اور SSH tunnel کے ذریعے اس تک رسائی حاصل کریں:

    ports:
      - "51820:51820/udp"
      - "127.0.0.1:51821:51821/tcp"
    environment:
      - INSECURE=true

پھر اپنے laptop سے:

ssh -L 51821:127.0.0.1:51821 youruser@your.server.address

اپنے laptop کے browser میں http://127.0.0.1:51821 کھولیں۔ Traffic، SSH کے ذریعے encrypted رہتا ہے اور یہ port کسی اور کو جواب نہیں دیتا۔ INSECURE=true صرف session cookie سے Secure flag ہٹاتا ہے تاکہ browser اس plain HTTP address پر آپ کا login برقرار رکھے۔ یہاں یہ محفوظ ہے کیونکہ plain HTTP hop کبھی loopback interface سے باہر نہیں جاتا۔

UDP 51820 کھولیں، اور دونوں firewalls چیک کریں

WireGuard کو انٹرنیٹ سے قابل رسائی UDP 51820 درکار ہے۔ Docker یہ port publish کرتا ہے، لیکن بہت سے providers VPS کے سامنے الگ network firewall رکھتے ہیں، جس کا Docker کو علم نہیں ہوتا۔ دونوں جگہ یہ port کھولیں۔ اگر آپ host firewall کو ufw کے ذریعے manage کرتے ہیں تو VPS کے لیے بنیادی ufw rules خود nftables ہاتھ سے لکھنے کے مقابلے میں مختصر طریقہ ہے۔

چیک کریں کہ container واقعی listening کر رہا ہے:

sudo ss -ulnp | grep 51820

آپ کو listening UDP socket نظر آنا چاہیے۔ اگر اس line پر کچھ بھی نہ ہو تو container نے interface شروع نہیں کیا، اور sudo docker compose logs wg-easy وجہ بتا دے گا۔

فون پر client بنائیں اور scan کریں

UI میں ایک client بنائیں اور اسے ایسا نام دیں جسے آپ بعد میں آسانی سے پہچان سکیں، مثلاً اس device کا نام جس سے یہ متعلق ہے۔ wg-easy اگلا دستیاب tunnel address خود مختص کرتا ہے اور آپ کے لیے key pair تیار کرتا ہے۔ ہر client row میں QR code اور download کے لیے .conf file موجود ہوتی ہے۔

فون پر official WireGuard app install کریں، QR code سے tunnel شامل کرنے کا انتخاب کریں، اور camera کو اپنی screen پر موجود code کی طرف کریں۔ Tunnel اسی نام کے ساتھ ظاہر ہوگا جو آپ نے درج کیا تھا۔ اسے فعال کریں۔ اس کے بعد UI میں client row transfer counters اور حالیہ handshake time دکھانا شروع کر دے گی۔ جب فون tunnel سے منسلک ہو جائے تو وہ ان services تک رسائی حاصل کر سکتا ہے جنہیں آپ نے internet پر publish نہیں کیا۔ اسی طرح فون کہیں سے بھی self-hosted photo server پر upload کرتا رہ سکتا ہے، جبکہ اس server کا دنیا کے لیے کوئی port کھلا نہیں ہوتا۔ یہی طریقہ media کے لیے بھی کام کرتا ہے۔ 90s video store کے طور پر دوبارہ بنایا گیا Jellyfin library hotel room سے browse کرنے کے لیے مفید ہے، جبکہ یہ آپ کے LAN کی طرح private رہتی ہے۔ اسی tunnel پر alerts بھی دوسری سمت میں کام کرتے ہیں۔ self-hosted ntfy server backup job fail ہوتے ہی اس فون پر message push کر سکتا ہے، اور اسے public internet سے آنے والی کسی request کا جواب دینے کی ضرورت نہیں ہوتی۔

جو client enable کرنے کے بعد کوئی handshake نہیں دکھاتا، وہ server تک بالکل نہیں پہنچ رہا۔ اس کی وجہ UDP 51820 ہو سکتی ہے، جو provider firewall پر مسدود ہو، یا config میں شامل endpoint address غلط ہو سکتا ہے۔ جو client handshake دکھاتا ہے لیکن internet کام نہیں کرتا، اس میں مسئلہ forwarding یا DNS کا ہوتا ہے۔

Desktop پر .conf file download کریں اور اسے دوبارہ ٹائپ کرنے کے بجائے WireGuard client میں import کریں۔ اس file میں private key صرف ایک بار generate اور صرف ایک بار دکھائی جاتی ہے۔ اس file کو اسی طرح محفوظ رکھیں جیسے آپ SSH private key کو محفوظ رکھتے ہیں۔

UI سے آگے بڑھنے کا وقت

جب تک آپ کے peers افراد اور phones ہوں، wg-easy موزوں tool ہے۔ UI کے ذریعے config files میں ترمیم کرنے کے مقابلے میں کام تیزی سے ہوتا ہے، اور گم شدہ phone کو ایک click سے revoke کیا جا سکتا ہے۔

اس کی حدود اس وقت سامنے آتی ہیں جب آپ ایسا کچھ کرنا چاہیں جسے UI model نہیں کرتا۔ Site-to-site routing عموماً پہلی بڑی رکاوٹ ہوتی ہے۔ اس میں peer کا AllowedIPs کسی ایک address کے بجائے پورے remote subnet کا احاطہ کرتا ہے۔ Split tunnels میں ہر peer کے لیے routing rules، یا آپ کے provisioning tool سے تیار کردہ config، اگلا مرحلہ ہے۔ اس مقام پر دستی طور پر لکھا گیا setup زیادہ مشکل نہیں ہوتا؛ طریقہ صرف مختلف ہوتا ہے، اور سادہ WireGuard guide میں یہی tunnel wg0.conf سے بنانے کا طریقہ دکھایا گیا ہے۔ اگر آپ control plane چلانا ہی بند کرنا چاہیں تو WireGuard اور Tailscale کا موازنہ managed option کی وضاحت کرتا ہے۔ یہ تبادلہ مناسب ہے یا نہیں، اس کا انحصار اس بات پر ہے کہ coordination server حقیقت میں کن وسائل تک پہنچ سکتا ہے۔ اپنے network کا اختیار اسے دینے سے پہلے Tailscale کا trust model پڑھنا مفید ہے۔ اگلا سوال عموماً cost کا ہوتا ہے۔ Tailscale کا free plan حقیقت میں کیا شامل کرتا ہے کے مطابق non-commercial use کے لیے زیادہ سے زیادہ چھ users بلا معاوضہ شامل ہوتے ہیں۔ اس لیے household کو کچھ ادا نہیں کرنا پڑتا، جبکہ small business team اہل نہیں ہوتی، چاہے اس میں کتنے ہی کم افراد ہوں۔ اس حد کے بعد billing devices کے بجائے users کی تعداد کے حساب سے ہوتی ہے۔ یہ اس VPS کے bill سے مختلف طریقہ ہے جس کی ادائیگی آپ پہلے ہی کر رہے ہیں۔ اس لیے team migrate کرنے سے پہلے free plan سے آگے بڑھنے پر Tailscale کی لاگت میں دی گئی رقم ضرور دیکھیں۔ آپ نے ابھی جو full tunnel بنایا ہے، اس کا وہاں براہ راست متبادل موجود ہے۔ VPS کو Tailscale exit node کے طور پر advertise کرنا server کے ذریعے باہر جانے والا وہی route فراہم کرتا ہے۔ فرق یہ ہے کہ اسے ہر client config میں لکھنے کے بجائے admin console میں approve کیا جاتا ہے۔ Subnet کے لیے بھی متبادل موجود ہے۔ VPS سے پورے private network کو advertise کرنا اس network کو tailnet کے ہر device تک پہنچا دیتا ہے، اور ہر peer کے لیے AllowedIPs میں ترمیم کرنے کی ضرورت نہیں رہتی؛ یہی ضرورت آپ کو UI سے آگے لے گئی تھی۔ اگر آپ dashboard اور automatic mesh routing چاہتے ہیں، لیکن کسی دوسرے کے coordination server پر انحصار نہیں کرنا چاہتے، تو VPS پر اپنا NetBird server چلانا control plane کو آپ کے اپنے hardware پر رکھتا ہے۔ اس کے بدلے DNS اور TLS setup کرنا پڑتا ہے، جس کی ضرورت wg-easy میں نہیں تھی۔

اگر اوپر کا compose syntax، WireGuard کے بجائے، آپ کے لیے نیا حصہ تھا، تو VPS پر Docker Compose کی بنیادی باتیں file format اور روزمرہ commands کی وضاحت کرتی ہیں۔

FAQ

Why does wg-easy ignore my WG_HOST and PASSWORD_HASH?

یہ variables wg-easy 14 سے متعلق ہیں۔ Version 15 ازسرنو تحریر کیا گیا ہے، اور upstream نے تقریباً تمام configuration web UI کے admin panel میں منتقل کر دی ہے۔ Container کسی بھی variable کو نہیں پڑھتا، اس لیے یہ معمول کے مطابق start ہوتا ہے اور پہلے visit پر آپ سے admin account بنانے کو کہتا ہے۔ Setup page پر client-facing host address درج کریں۔

Do I need SYS_MODULE if my kernel already has WireGuard?

نہیں۔ SYS_MODULE اور /lib/modules mount اس لیے موجود ہیں کہ host پر module موجود نہ ہونے کی صورت میں container اسے load کر سکے۔ جس host پر sudo modprobe wireguard پہلے ہی کامیاب ہو، وہاں یہ capability استعمال نہیں ہوتی۔ اسے ہٹانا hardening کا ایک مناسب قدم ہے، اور NET_ADMIN بہرحال ضروری رہتا ہے۔

The client connects but there is no internet. What is wrong?

Traffic کے بغیر handshake تقریباً ہمیشہ forwarding کا مسئلہ ہوتا ہے۔ تصدیق کریں کہ net.ipv4.ip_forward=1 اور net.ipv4.conf.all.src_valid_mark=1 اب بھی compose file میں موجود ہیں، کیونکہ ہاتھ سے edit کی گئی copy میں یہ اکثر حذف ہو جاتے ہیں۔ اگر forwarding فعال ہے تو client کو موصول ہونے والے DNS server کو check کریں۔ ایسا tunnel جو تمام traffic VPN کے ذریعے بھیجے، لیکن ایسے DNS server کی طرف اشارہ کرے جس تک اب رسائی نہ ہو، browser میں بالکل dead connection جیسا دکھائی دیتا ہے۔

How do I back up my clients?

تمام data etc_wireguard named volume میں موجود ہوتا ہے۔ Version 15 میں اس کا مطلب container کے اندر /etc/wireguard/wg-easy.db پر موجود SQLite database ہے۔ v15 کی documentation میں backup یا export feature بیان نہیں کیا گیا، اس لیے خود volume کا backup لیں: docker compose down چلائیں، volume کا content server سے باہر کسی محفوظ جگہ پر copy کریں، پھر docker compose up -d کے ساتھ stack دوبارہ start کریں۔ یہ کام ہر upgrade سے پہلے کریں۔ پرانی guides میں مذکور wg0.json file wg-easy 14 سے متعلق ہے۔ v14 کا backup button اسی file کو export کرتا ہے، جبکہ v15 میں اس کا واحد استعمال setup wizard میں پرانی installation migrate کرتے وقت upload کی جانے والی file کے طور پر ہے۔

Can I run wg-easy behind a reverse proxy?

ہاں۔ Proxy کو web UI port کے سامنے رکھیں، وہیں TLS terminate کریں، اور INSECURE کو unset رہنے دیں۔ Container proxy سے آنے والے plain HTTP hop کو براہِ راست قبول کرتا ہے، اور official Caddy اور Traefik examples میں INSECURE variable بالکل set نہیں کیا جاتا۔ چونکہ browser proxy سے HTTPS کے ذریعے بات کرتا ہے، اس لیے session cookie میں Secure flag برقرار رہنا چاہیے؛ INSECURE=true صرف یہی flag ہٹاتا ہے۔ UDP 51820 کو براہِ راست published رکھیں، کیونکہ VPN traffic UDP ہے اور HTTP proxy سے نہیں گزرتا۔

کیا یہ مضمون مفید تھا؟