Docker లో wg-easy WireGuard వెబ్ UI సెటప్

మీరు నిర్మించేది

wg-easy అనేది ఒకే Docker container గా నడిచే, web interface కలిగిన WireGuard. ఇది మీ తరఫున WireGuard interface ను నిర్వహిస్తుంది. Clients ను సృష్టించడానికి browser UI ను కూడా అందిస్తుంది. మీరు సృష్టించే ప్రతి client కు ఒక config file మరియు QR code లభిస్తాయి. అందువల్ల phone లో camera ను screen వైపు చూపించడం ద్వారా VPN కు connect చేయవచ్చు.

Tunnel సాధారణ WireGuard tunnel గానే ఉంటుంది. Kernel module packets ను తరలిస్తుంది. కాబట్టి స్వయంగా రాసిన setup తో ఉన్న throughput నే ఇక్కడ కూడా పొందుతారు. దీనివల్ల client lifecycle నిర్వహణ సులభమవుతుంది: SSH ద్వారా config file ను edit చేయకుండానే peers ను add, disable, delete చేయవచ్చు. అయితే ఆ config పై direct control ను వదులుకోవాలి. దీనికి సంబంధించిన విధానం VPS పై manual WireGuard setup లో ఉంది.

మీకు public IPv4 address కలిగిన KVM VPS, Compose plugin తో కూడిన Docker Engine, మరియు root access అవసరం. OpenVZ లేదా LXC వంటి host kernel ను share చేసే 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 గా set చేసేవారు. Version 15 పూర్తిగా పునఃరచించబడింది. v15, v14లో ఉన్న అదే environment variables ను ఉపయోగించదని, వాటిలో ఎక్కువ భాగం web UIలోని admin panel కు తరలించబడ్డాయని official migration notes స్పష్టంగా చెబుతున్నాయి.

అందువల్ల WG_HOST మరియు PASSWORD_HASH ఇకపై ఎలాంటి ప్రభావం చూపవు. మీరు పాత compose file ను copy చేస్తే container ప్రారంభమవుతుంది, ఆ lines ను పరిగణనలోకి తీసుకోదు, తరువాత browserలో admin account సృష్టించమని అడుగుతుంది. ఇది bug కాదు. ఇదే కొత్త setup flow.

July 2026 నాటికి pin చేయాల్సిన major tag 15. latest ఉపయోగించకుండా major version ను pin చేయండి. Major upgrade on-disk config format ను మార్చుతుంది. అందువల్ల rollback సరిగ్గా జరగదు.

Compose ఫైల్

Stack కోసం ఒక directoryని సృష్టించి, అధికారిక compose ఫైల్‌ను అందులో రాయండి. ఇది upstream ఫైల్. ఎలాంటి మార్పులు చేయలేదు.

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 అనేది server key మరియు మీరు సృష్టించే ప్రతి clientను కలిగి ఉండే named volume. ఆ 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 -f

docker compose up మరియు docker compose down ఉపయోగించండి; start మరియు stop ఉపయోగించవద్దు. వేర్వేరు settings తో సృష్టించిన container పై start అమలు చేస్తే network స్థితి అసంగతంగా మారుతుందని upstream హెచ్చరిస్తోంది. reboot తర్వాత stack మళ్లీ ప్రారంభం కావాలంటే restart: unless-stopped ఇప్పటికే ఆ పని చేస్తుంది. ఆ policy ఏం చేస్తుందో, ఏ హామీ ఇవ్వదో compose services యొక్క boot ప్రవర్తన వివరిస్తుంది.

Web UI TCP 51821 పై వినేలా ఉంటుంది. మొదటిసారి తెరిచినప్పుడు setup page కనిపిస్తుంది. అక్కడ admin ఖాతాను సృష్టించి, clients server ను చేరుకోవడానికి ఉపయోగించే host address ను నిర్ధారించాలి. ఆ host address ప్రతి client config లోని Endpoint line లోకి వెళ్తుంది. అందువల్ల అది VPS యొక్క public IP లేదా DNS పేరు అయి ఉండాలి. అది తప్పుగా ఉంటే, phone కు అందించే QR code చేరుకోలేని చిరునామాను సూచిస్తుంది. అప్పుడు handshake ఎప్పటికీ పూర్తికాదు.

ఆ port గురించి మరో విషయం ఉంది: INSECURE=true ను set చేయకపోతే wg-easy 15 plain HTTP ను నిరాకరిస్తుంది. untrusted certificate తో HTTPS ద్వారా దాన్ని చేరుకోవడం లేదా దాని ముందు reverse proxy వద్ద TLS termination చేయడం రెండూ సరైనవే. default settings తో http:// ద్వారా దాన్ని చేరుకోవడం సరైనది కాదు.

UI port ను internet కు publish చేయవద్దు

Compose file ప్రతి interface పై 51821 ను publish చేస్తోంది. ఇది మీ traffic ను route చేయగల సిస్టమ్‌కు సంబంధించిన login page. అందువల్ల దీనిని అందరికీ open గా ఉంచకూడదు. Dockerలో port publish చేసినప్పుడు, అది DOCKER chain లో rules రాస్తుంది. ఈ chain ufw కంటే ముందుగా evaluate అవుతుంది. అందువల్ల ufw deny rule ఆ port ను మూసివేయదు. ఈ సమస్యను ప్రత్యేకంగా అర్థం చేసుకోవాలి. Docker published 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 ద్వారా encrypted అవుతుంది. ఈ port ఇతరులకు స్పందించదు. ఇక్కడ INSECURE=true సురక్షితం, ఎందుకంటే 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 51820

Listeningలో ఉన్న 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 సరైన సాధనం. Configuration files ను సవరించడం కంటే UI వేగంగా ఉంటుంది. పోయిన phone ను ఒక click తో revoke చేయవచ్చు.

UIలో model చేయలేని పని కావాలనుకున్నప్పుడు దాని పరిమితులు కనిపిస్తాయి. ఒక peer యొక్క AllowedIPs ఒక్క address కు బదులుగా మొత్తం remote subnet ను cover చేసే site-to-site routing సాధారణంగా ఎదురయ్యే మొదటి పరిమితి. ప్రతి 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 చదవడం మంచిది. తరువాత సాధారణంగా cost గురించి ప్రశ్న వస్తుంది. Tailscale free plan వాస్తవంగా ఏమి కలిగి ఉంది అనే వివరణ household లేదా చిన్న team దానికి ఏమీ చెల్లించాల్సిన అవసరం లేకపోవచ్చని చూపిస్తుంది. ఆ పరిమితి దాటిన తరువాత billing devices బదులుగా users ను లెక్కిస్తుంది. మీరు ఇప్పటికే చెల్లిస్తున్న VPS కంటే ఇది భిన్నమైన billing విధానం. అందువల్ల 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 నుంచి మిమ్మల్ని దూరం చేసిన per-peer AllowedIPs editing అవసరం ఉండదు. ఆ 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 కు కనిపించే 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 ద్వారా పంపే tunnel, కానీ ఇక చేరుకోలేని DNS server ను సూచిస్తే, browser లో అది connection పూర్తిగా పనిచేయనట్టుగా కనిపిస్తుంది.

నా clients కు backup ఎలా తీసుకోవాలి?

మొత్తం data etc_wireguard named volume లోని wg0.json file లో ఉంటుంది. UI లో అదే data ను export చేసే backup button కూడా ఉంది. ఏ upgrade కు ముందైనా ఆ file ను server వెలుపల ఉన్న ప్రదేశానికి copy చేయండి. కొత్త container setup సమయంలో upload చేయడం ద్వారా restore చేయవచ్చు.

Reverse proxy వెనుక wg-easy ను నడపవచ్చా?

అవును. TCP 51821 ముందు proxy ను ఉంచి, అక్కడే TLS termination చేయండి. Proxy నుంచి వచ్చే plain HTTP hop ను container స్వీకరించేలా INSECURE=true ను container పై సెట్ చేయండి. UDP 51820 ను నేరుగా publish చేయండి. VPN traffic UDP పై నడుస్తుంది కాబట్టి అది HTTP proxy ద్వారా వెళ్లదు.