Docker లో wg-easy WireGuard వెబ్ UI సెటప్
Docker Compose తో wg-easy ద్వారా WireGuard నడపండి: అవసరమైన ports, NET_ADMIN, ముఖ్యమైన sysctls, అలాగే phones కోసం QR code onboarding వివరాలను తెలుసుకోండి.
మీరు నిర్మించేది
wg-easy అనేది web interface తో కూడిన WireGuard. ఇది ఒకే Docker container గా నడుస్తుంది. ఇది మీ తరఫున WireGuard interface ను నిర్వహిస్తుంది. clients ను సృష్టించడానికి browser UI ను కూడా అందిస్తుంది. మీరు సృష్టించే ప్రతి client కు config file మరియు QR code లభిస్తాయి. అందువల్ల phone ను VPN కు అనుసంధానించడానికి screen పై ఉన్న code ను camera తో scan చేయవచ్చు.
Tunnel స్వయంగా సాధారణ WireGuard tunnel గానే ఉంటుంది. Packets ను kernel module తరలిస్తుంది. అందువల్ల throughput ను చేతితో రాసిన setup తో సమానంగా పొందవచ్చు. మీరు పొందేది client lifecycle నిర్వహణ. SSH ద్వారా config file ను edit చేయకుండా peers ను add, disable, delete చేయవచ్చు. మీరు వదులుకునేది ఆ config పై ప్రత్యక్ష నియంత్రణ. దీని గురించి VPS పై manual WireGuard setup లో వివరించబడింది.
మీకు నిర్వహించగల Linux host అవసరం. ఉదాహరణకు KVM VPS సరిపోతుంది. దానికి public IP address లేదా ఆ host వైపు చూపించే domain name ఉండాలి. x86_64 లేదా arm64 CPU, Compose plugin తో కూడిన Docker Engine, root access కూడా అవసరం. OpenVZ లేదా LXC వంటి host kernel ను భాగస్వామ్యం చేసే container virtualisation సాధారణంగా WireGuard module ను load చేయలేవు. అందువల్ల container interface ను ప్రారంభించడంలో విఫలమవుతుంది.
Version 15లో settings ను environment నుండి తొలగించారు
మీకు కనిపించే చాలా guides wg-easy 14 కోసం రాసినవి. అందులో WG_HOST కు మీ server address ను, PASSWORD_HASH కు admin password యొక్క bcrypt hash ను environment variables గా సెట్ చేసేవారు. Version 15 పూర్తిగా పునర్రచించబడింది. v15, v14లో ఉన్న అదే environment variables ను ఉపయోగించదని, వాటిలో ఎక్కువ భాగం web UIలోని admin panelకు మార్చారని అధికారిక migration notes స్పష్టంగా చెబుతున్నాయి.
కాబట్టి WG_HOST మరియు PASSWORD_HASH ఇకపై ఎలాంటి ప్రభావం చూపవు. మీరు పాత compose file ను copy చేస్తే container ప్రారంభమవుతుంది, ఆ lines ను పట్టించుకోదు, తరువాత browserలో admin account సృష్టించమని అడుగుతుంది. ఇది bug కాదు. ఇదే కొత్త setup flow.
October 2026 నాటికి pin చేయాల్సిన major tag 15. latest ఉపయోగించకుండా major version ను pin చేయండి. Major upgrade వల్ల diskలోని config format మారుతుంది, కాబట్టి rollback సరిగ్గా పనిచేయదు. 15కి మారినప్పుడు v14లోని JSON file స్థానంలో SQLite database వచ్చింది.
Compose ఫైల్
Stack కోసం ఒక directory సృష్టించి, అధికారిక compose ఫైల్ను అందులో రాయండి. ఇది upstream ఫైల్. వ్యాఖ్యలుగా ఉంచిన optional 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::/64etc_wireguard అనేది server key మరియు మీరు సృష్టించే ప్రతి client ను నిల్వ చేసే named volume. ఇవి SQLite database wg-easy.db లో నిల్వ అవుతాయి. ఆ volume కు backup తీసుకోండి. లేకపోతే rebuild సమయంలో మీ peers అన్నీ తొలగిపోతాయి. ఆ files ను host filesystem లో చూడాలనుకుంటే, దాని స్థానంలో bind mount ఉపయోగించవచ్చు. అయితే ముందుగా bind mounts మరియు named volumes మధ్య తేడా చదవండి, ఎందుకంటే వాటి permissions వేర్వేరుగా పనిచేస్తాయి.
NET_ADMIN, SYS_MODULE మరియు sysctls ఎందుకు అవసరం
డిఫాల్ట్గా container కు network stack ను మార్చే అనుమతి ఉండదు. ఈ lines లో ప్రతి ఒక్కటి ఒక నిర్దిష్ట అడ్డంకిని తొలగిస్తుంది.
NET_ADMIN ద్వారా container wg0 interface ను సృష్టించి, దానికి address కేటాయించి, routes రాయగలదు. ఇది లేకపోతే interface ను ప్రారంభించే సమయంలో container start అయి వెంటనే ఆగిపోతుంది, ఎందుకంటే ip link add wg0 type wireguard, Operation not permitted ను తిరిగి ఇస్తుంది.
SYS_MODULE మరియు read-only /lib/modules mount కలిసి, host ఇప్పటికే WireGuard kernel module ను load చేయకపోతే container దాన్ని load చేయడానికి అనుమతిస్తాయి. ఈ module image లో కాకుండా host kernel లో ఉంటుంది. అందుకే host directory container కు కనిపించాలి. ఆధునిక kernel లో ఈ module సాధారణంగా built in గా ఉంటుంది. Host పై sudo modprobe wireguard && echo ok ను అమలు చేసి దాన్ని నిర్ధారించవచ్చు.
net.ipv4.ip_forward=1, box కు స్వయంగా ఉద్దేశించని packets ను kernel forward చేయేలా చేస్తుంది. ఇది లేకపోతే client connect అవుతుంది, handshake విజయవంతమవుతుంది, కానీ internet కు వెళ్లే ప్రతి packet drop అవుతుంది. అందువల్ల VPN connected గా కనిపించినప్పటికీ ping 1.1.1.1 timeout అవుతుంది.
net.ipv4.conf.all.src_valid_mark=1 ప్రజలను ఎక్కువగా ఆశ్చర్యపరిచే setting. WireGuard తన outgoing packets ను mark చేస్తుంది, తద్వారా అవి తిరిగి tunnel లోకి route కావు. Strict reverse path filtering లో source address కు expected route సరిపోలకపోతే packet drop అవుతుంది. ఈ sysctl marked packets ను kernel అంగీకరించేలా చేస్తుంది. అందువల్ల full tunnel తన traffic ను తానే అడ్డుకోదు.
దీన్ని ప్రారంభించి admin ఖాతాను సృష్టించండి
cd /etc/docker/containers/wg-easy
sudo docker compose up -d
sudo docker compose logs -fdocker compose up మరియు docker compose down ఉపయోగించండి; start మరియు stop ఉపయోగించవద్దు. ఇప్పటికే ఉన్న containers ను మాత్రమే start restart చేస్తుంది. అందువల్ల network మరియు sysctl settings సహా compose file లో మీరు చేసిన మార్పులు వర్తించవు. మారిన వాటిని up మళ్లీ సృష్టిస్తుంది. reboot తర్వాత stack మళ్లీ అందుబాటులోకి రావాలంటే restart: unless-stopped ఇప్పటికే ఆ విషయాన్ని నిర్వహిస్తుంది. compose services ప్రారంభ సమయంలో ఎలా ప్రవర్తిస్తాయో ఆ విధానం ఏమి హామీ ఇస్తుందో, ఏమి ఇవ్వదో వివరిస్తుంది.
Web UI TCP 51821 పై listen చేస్తుంది. మొదటిసారి తెరిచినప్పుడు setup page కనిపిస్తుంది. అక్కడ admin ఖాతాను సృష్టించి, clients server ను చేరడానికి ఉపయోగించే host address ను నిర్ధారించాలి. ఆ host address ప్రతి client config లోని Endpoint line లోకి వెళ్తుంది. అందువల్ల అది VPS యొక్క public IP లేదా DNS name అయి ఉండాలి. అది తప్పుగా ఉంటే, phone కు అందించే QR code చేరుకోలేని చిరునామాను సూచిస్తుంది. అప్పుడు handshake ఎప్పటికీ పూర్తికాదు.
ఆ port గురించి మరో విషయం ఉంది. wg-easy స్వయంగా TLS ను అందించదు. Plain HTTP ను కూడా తిరస్కరించదు. http:// ద్వారా UI ఇంకా load అవుతుంది, warning banner కూడా చూపిస్తుంది. Default మార్పు session cookie కు సంబంధించినది. ఆ cookie లో Secure flag ఉంటుంది. అందువల్ల public address పై plain HTTP ద్వారా UI ను తెరిచే browser ఆ cookie ను discard చేస్తుంది. దాంతో login నిలవదు. INSECURE=true ఆ flag ను తొలగిస్తుంది; ఇతర మార్పులు ఏవీ చేయదు. TLS termination చేసే reverse proxy ను ముందు ఉంచితే, self-signed certificate అయినా సరే, wg-easy లో ఎలాంటి మార్పు అవసరం లేదు.
UI port ను internet కు ప్రచురించవద్దు
Compose file ప్రతి interface పై 51821 ను ప్రచురిస్తుంది. మీ network traffic ను route చేయగల సిస్టమ్కు ఇది login page. అందువల్ల దీనిని అందరికీ తెరిచి ఉంచకూడదు. Docker లో port ను ప్రచురించినప్పుడు, అది నియమాలను DOCKER chain లోకి రాస్తుంది. ఈ chain ను ufw కంటే ముందుగా evaluate చేస్తారు. కాబట్టి ufw deny rule ఆ port ను మూసివేయదు. ఈ సమస్యను ప్రత్యేకంగా అర్థం చేసుకోవాలి. Docker ప్రచురించిన ports ufw ను ఎందుకు పట్టించుకోవు లో దీనిపై పూర్తి వివరణ ఉంది.
సులభమైన పరిష్కారం UI ను loopback కు bind చేసి, SSH tunnel ద్వారా దాన్ని access చేయడం:
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 ను open చేయండి. Traffic ను SSH encrypt చేస్తుంది. ఆ 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 ముందు Dockerకు తెలియని ప్రత్యేక network firewallను ఉంచుతాయి. రెండు చోట్లా ఈ portను తెరవండి. ufwతో host firewallను నిర్వహిస్తే, nftablesను చేతితో రాయడం కంటే VPS కోసం ప్రాథమిక ufw నియమాలు ఉపయోగించడం వేగవంతమైన మార్గం.
Container వాస్తవంగా listeningలో ఉందో తనిఖీ చేయండి:
sudo ss -ulnp | grep 51820Listeningలో ఉన్న UDP socket కనిపించాలి. ఆ పంక్తిలో ఏదీ కనిపించకపోతే, container interfaceను ప్రారంభించలేదు. కారణాన్ని sudo docker compose logs wg-easy చూపిస్తుంది.
క్లయెంట్ను సృష్టించి ఫోన్లో స్కాన్ చేయండి
UIలో ఒక క్లయెంట్ను సృష్టించి, తరువాత గుర్తించగలిగే పేరును ఇవ్వండి. ఉదాహరణకు, అది చెందిన పరికరం పేరును ఉపయోగించవచ్చు. wg-easy తదుపరి ఖాళీ tunnel address ను కేటాయించి, key pair ను మీ కోసం రూపొందిస్తుంది. ప్రతి క్లయెంట్ వరుసలో QR code మరియు డౌన్లోడ్ చేయగల .conf file ఉంటాయి.
ఫోన్లో అధికారిక WireGuard app ను ఇన్స్టాల్ చేసి, QR code నుంచి tunnel ను జోడించే ఎంపికను ఎంచుకోండి. తరువాత మీ screen పై ఉన్న code వైపు camera ను చూపండి. మీరు ఇచ్చిన పేరుతో tunnel కనిపిస్తుంది. దాన్ని ఆన్ చేయండి. UIలోని క్లయెంట్ వరుస transfer counters మరియు ఇటీవలి handshake సమయాన్ని చూపించడం ప్రారంభిస్తుంది. ఫోన్ tunnel కు కనెక్ట్ అయిన తర్వాత, మీరు internetలో ఎప్పుడూ public చేయని services ను కూడా అది చేరుకోగలదు. అందువల్ల server కు ప్రపంచం నుంచి ఏ port కూడా open చేయకుండా, ఫోన్ ఎక్కడి నుంచైనా స్వయంగా నిర్వహించే photo server కు upload చేస్తూనే ఉంటుంది. ఇదే విధానాన్ని media కోసం కూడా ఉపయోగించవచ్చు. 90s video storeగా మళ్లీ రూపొందించిన Jellyfin library ను hotel room నుంచి browse చేయడం సౌకర్యంగా ఉంటుంది; అదే సమయంలో అది మీ LANలో ఉన్నంత privateగా ఉంటుంది. అదే tunnel ద్వారా alerts ను వ్యతిరేక దిశలో కూడా పంపవచ్చు. స్వయంగా నిర్వహించే ntfy server backup job విఫలమైన వెంటనే ఆ ఫోన్కు message పంపగలదు. ఇందుకోసం public internet నుంచి వచ్చే request కు అది ఎప్పుడూ సమాధానం ఇవ్వాల్సిన అవసరం లేదు.
క్లయెంట్ను enable చేసిన తర్వాత handshake కనిపించకపోతే, అది server ను అసలు చేరుకోవడం లేదు. సమస్య UDP 51820 వద్ద ఉండవచ్చు. ఇది provider firewallలో లేదా configలో ముందే పొందుపరిచిన endpoint addressలో ఉండవచ్చు. handshake కనిపించినా internet పనిచేయకపోతే, సమస్య forwarding లేదా DNSలో ఉండవచ్చు.
Desktopలో .conf file ను డౌన్లోడ్ చేసి, దాన్ని మళ్లీ టైప్ చేయకుండా WireGuard clientలో import చేయండి. ఆ fileలోని private key ఒక్కసారి మాత్రమే రూపొందించబడుతుంది మరియు ఒక్కసారి మాత్రమే చూపబడుతుంది. ఆ fileను SSH private keyను ఎలా సంరక్షిస్తారో అలాగే సంరక్షించండి.
UIని దాటి వెళ్లాల్సిన సమయం
మీ peers మనుషులు మరియు phones ఉన్నంత వరకు wg-easy సరైన సాధనం. Config files ను నేరుగా సవరించడం కంటే UI వేగంగా ఉంటుంది. పోయిన phone కు సంబంధించిన access ను ఒక్క click తో revoke చేయవచ్చు.
UIలో model చేయలేని అంశాలు మీకు అవసరమైనప్పుడు దాని పరిమితులు కనిపిస్తాయి. Site-to-site routing సాధారణంగా మొదటి అడ్డంకి. ఇందులో peer యొక్క AllowedIPs ఒకే address కు బదులుగా మొత్తం remote subnet ను కవర్ చేస్తుంది. ప్రతి peer కు వేర్వేరు routing rules ఉన్న split tunnels లేదా మీ provisioning tool రూపొందించిన config తదుపరి దశలు. ఆ దశలో చేతితో రాసే setup కష్టం కాదు; అది కేవలం భిన్నంగా ఉంటుంది. సాధారణ WireGuard guide లో wg0.conf ఉపయోగించి అదే tunnel ను రూపొందించే విధానం ఉంది. Control plane ను పూర్తిగా నిర్వహించడం ఆపాలనుకుంటే, WireGuard మరియు Tailscale పోలిక managed option గురించి వివరిస్తుంది. Coordination server వాస్తవంగా ఏ network ను చేరుకోగలదో దాని ఆధారంగా ఆ మార్పిడి సముచితమా కాదా నిర్ణయించాలి. మీ network ను దానికి అప్పగించే ముందు Tailscale trust model ను చదవడం మంచిది. తర్వాత సాధారణంగా ఖర్చు గురించిన ప్రశ్న వస్తుంది. Tailscale free plan వాస్తవంగా ఏమి అందిస్తుంది అనే దాని ప్రకారం non-commercial use కోసం గరిష్టంగా ఆరుగురు users కు ఎటువంటి ఖర్చు ఉండదు. అందువల్ల household ఏమీ చెల్లించదు. కానీ చిన్న business team లో ఎంత తక్కువ మంది ఉన్నా అది అర్హత పొందదు. ఆ పరిమితిని దాటిన తర్వాత billing devices బదులుగా users సంఖ్యను లెక్కిస్తుంది. మీరు ఇప్పటికే చెల్లిస్తున్న VPS బిల్లుతో పోలిస్తే ఇది వేరే రకమైన ఖర్చు. కాబట్టి 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 కు అందించవచ్చు. UI నుంచి మిమ్మల్ని దూరం చేసిన ప్రతి peer కు AllowedIPs ను విడిగా సవరించాల్సిన అవసరం ఉండదు. Dashboard మరియు automatic mesh routing కావాలి, కానీ ఇతరుల coordination server వద్దనుకుంటే, VPS పై మీ స్వంత NetBird server నడపడం ద్వారా control plane ను మీ సొంత hardware పై ఉంచుకోవచ్చు. అయితే దీనికి wg-easy లో అవసరం లేని DNS మరియు TLS setup చేయాలి.
పై compose syntax మాత్రమే మీకు కొత్తగా అనిపించి, WireGuard భాగం కాదు అనుకుంటే, VPS పై Docker Compose ప్రాథమికాలు file format మరియు రోజువారీ commands ను వివరిస్తుంది.
FAQ
wg-easy నా WG_HOST మరియు PASSWORD_HASH ను ఎందుకు పట్టించుకోదు?
ఆ variables wg-easy 14 కు సంబంధించినవి. Version 15 పూర్తిగా పునర్రచించబడింది. Upstream దాదాపు మొత్తం configuration ను web UI లోని admin panel కు మార్చింది. Container ఈ రెండు variables లో దేనినీ చదవదు. అందువల్ల అది సాధారణంగా ప్రారంభమై, మొదటి సారి తెరిచినప్పుడు admin account సృష్టించమని అడుగుతుంది. Setup page లో client-facing host address ను సెట్ చేయండి.
నా kernel లో WireGuard ఇప్పటికే ఉంటే SYS_MODULE అవసరమా?
లేదు. SYS_MODULE మరియు /lib/modules mount లు host లో module అందుబాటులో లేనప్పుడు container దాన్ని load చేయడానికి ఉంటాయి. sudo modprobe wireguard ఇప్పటికే విజయవంతంగా నడిచే host లో ఈ capability ఉపయోగించబడదు. దీన్ని తొలగించడం ఒక సముచిత hardening చర్య. అయితే NET_ADMIN ఏ పరిస్థితిలోనైనా అవసరం.
Client connect అవుతోంది, కానీ internet లేదు. సమస్య ఏమిటి?
Traffic లేకుండా handshake కనిపిస్తే, దాదాపు ఎల్లప్పుడూ forwarding సమస్యే. net.ipv4.ip_forward=1 మరియు net.ipv4.conf.all.src_valid_mark=1 ఇప్పటికీ compose file లో ఉన్నాయో నిర్ధారించండి. చేతితో మార్చిన copy లో ఇవి తరచుగా పోతాయి. Forwarding సక్రియంగా ఉంటే, client కు అందిన DNS server ను పరిశీలించండి. మొత్తం traffic ను VPN ద్వారా పంపుతూ, ఇక చేరుకోలేని DNS server ను ఉపయోగించే tunnel, browser లో dead connection లాగానే కనిపిస్తుంది.
నా clients ను ఎలా backup చేయాలి?
అన్నీ etc_wireguard named volume లో ఉంటాయి. Version 15 లో container లోని /etc/wireguard/wg-easy.db వద్ద SQLite database ఉంటుంది. Version 15 docs లో backup లేదా export feature గురించి చెప్పలేదు. అందువల్ల volume ను నేరుగా backup చేయండి: docker compose down నడిపి, volume contents ను server వెలుపల ఉన్న ప్రదేశానికి copy చేయండి. తరువాత docker compose up -d తో stack ను మళ్లీ ప్రారంభించండి. ప్రతి upgrade కు ముందు ఇది చేయండి. పాత guides లో చెప్పే wg0.json file wg-easy 14 కు సంబంధించినది. v14 లో backup button export చేసేది ఇదే. v15 లో పాత install ను migrate చేసేటప్పుడు setup wizard లో upload చేసే file గా మాత్రమే ఇది ఉపయోగపడుతుంది.
Reverse proxy వెనుక wg-easy ను నడపవచ్చా?
అవును. Web UI port ముందు proxy ను ఉంచి, అక్కడే TLS terminate చేయండి. INSECURE ను unset గా ఉంచండి. Container proxy నుంచి వచ్చే plain HTTP hop ను అలాగే స్వీకరిస్తుంది. అధికారిక Caddy మరియు Traefik examples ఏ INSECURE variable ను సెట్ చేయవు. Browser proxy తో HTTPS ద్వారా మాట్లాడుతుంది కాబట్టి, session cookie లో Secure flag కొనసాగాలి. INSECURE=true తొలగించేది ఇదొక్కటే. UDP 51820 ను నేరుగా publish చేసి ఉంచండి. VPN traffic UDPపై ఉంటుంది కాబట్టి అది HTTP proxy ద్వారా వెళ్లదు.