Jinsi ya kuweka wg-easy na WireGuard kwenye Docker

Unachojenga

wg-easy ni WireGuard yenye kiolesura cha wavuti, inayofanya kazi kama container moja ya Docker. Inakusimamia kiolesura cha WireGuard na kuongeza UI ya kivinjari kwa ajili ya kuunda wateja (clients). Kila mteja unayemuunda anapata faili ya usanidi na QR code, hivyo simu inaweza kujiunga na VPN kwa kuelekeza kamera yake kwenye skrini.

Tundu (tunnel) lenyewe ni WireGuard ya kawaida. Moduli ya kernel ndiyo inayohamisha pakiti, kwa hivyo kasi ya upitishaji data ni sawa na usanidi uliofanywa kwa mikono. Unachopata ni mzunguko wa maisha wa mteja: kuongeza, kulemaza, na kufuta peers bila kuhariri faili ya usanidi kupitia SSH. Unachopoteza ni udhibiti wa moja kwa moja wa usanidi huo, ambao ndio mada ya usanidi wa WireGuard kwa mikono kwenye VPS.

Unahitaji KVM VPS yenye anwani ya umma ya IPv4, Docker Engine yenye Compose plugin, na ufikiaji wa root. Uboreshaji wa container (container virtualisation) unaoshiriki kernel ya host, kama vile OpenVZ au LXC, kwa kawaida hauwezi kupakia moduli ya WireGuard, na container itashindwa kuwasha kiolesura hicho.

Toleo la 15 limehamisha mipangilio kutoka kwenye environment

Miongozo mingi utakayopata iliandikwa kwa ajili ya wg-easy 14, ambapo uliweka WG_HOST kwenye anwani ya seva yako na PASSWORD_HASH kwenye bcrypt hash ya nenosiri la admin, zote zikiwa kama environment variables. Toleo la 15 ni andiko jipya. Maelezo rasmi ya uhamiaji yanasema wazi kuwa v15 haitumii environment variables zilezile kama v14, na kwamba nyingi kati ya hizo zimehamishiwa kwenye paneli ya admin katika web UI.

Kwa hivyo WG_HOST na PASSWORD_HASH hazifanyi kazi tena. Ukinakili faili ya zamani ya compose, container huanza, hupuuza mistari hiyo, kisha inakuomba uunde akaunti ya admin kwenye kivinjari. Hiyo si hitilafu (bug). Ni mtiririko mpya wa usanidi.

Kufikia Julai 2026, tag kuu ya kutumia ni 15. Weka toleo kuu badala ya kutumia latest, kwa sababu upgrade ya toleo kuu hubadilisha muundo wa config kwenye diski na haitarudi nyuma (roll back) kwa usalama.

Faili la compose

Tengeneza saraka kwa ajili ya stack hii na uandike faili rasmi la compose ndani yake. Hili ni faili la asili kutoka kwa msanidi, halijabadilishwa.

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

Yaliyomo yanaonekana hivi:

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 ni named volume inayohifadhi ufunguo wa seva na kila mteja unayemuunda. Hifadhi nakala ya volume hiyo, la sivyo ujenzi upya utafuta wenza wako wote. Ikiwa ungependa kuona faili hizo kwenye mfumo wa faili wa host, badilisha na utumie bind mount, na usome tofauti kati ya bind mounts na named volumes kabla ya kufanya hivyo, kwa sababu ruhusa hufanya kazi kwa njia tofauti.

Kwa nini inahitaji NET_ADMIN, SYS_MODULE na sysctls

Kwa kawaida, container hairuhusiwi kugusa network stack, na kila moja ya mistari hii huondoa kizuizi kimoja mahususi.

NET_ADMIN inaruhusu container kuunda interface ya wg0, kuipa anwani na kuandika routes. Bila hii, container huanza na kisha kufa wakati inajaribu kuwasha interface, kwa sababu ip link add wg0 type wireguard inarejesha Operation not permitted.

SYS_MODULE pamoja na mount ya /lib/modules inayoweza kusomwa pekee (read-only) inaruhusu container kupakia kernel module ya WireGuard ikiwa mwenyeji (host) haijapakia tayari. Module hiyo ipo kwenye kernel ya host, si ndani ya image, ndiyo maana saraka ya host lazima ionekane. Kwenye kernel ya kisasa, module hiyo kwa kawaida imejengwa ndani, na unaweza kuthibitisha kwa sudo modprobe wireguard && echo ok kwenye host.

net.ipv4.ip_forward=1 huifanya kernel kusambaza (forward) pakiti ambazo hazijaelekezwa kwenye mashine hiyo yenyewe. Bila hii, mteja huunganishwa, handshake inafanikiwa, na kisha kila pakiti inayoelekea kwenye Internet inatupwa, hivyo ping 1.1.1.1 inazidi muda (timeout) wakati VPN inaonekana kama imeunganishwa.

net.ipv4.conf.all.src_valid_mark=1 ndiyo inayowashangaza watu. WireGuard huweka alama kwenye pakiti zake zinazotoka ili zisielekezwe kurudi ndani ya tunnel. Uchunguzi mkali wa reverse path filtering huona pakiti ambayo anwani yake ya chanzo hailingani na route inayotarajiwa na kuitupa. Sysctl hii huiambia kernel ikubali pakiti zenye alama, jambo ambalo huzuia tunnel kamili kujivunja yenyewe.

Anzisha huduma na uunde akaunti ya msimamizi

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

Tumia docker compose up na docker compose down, badala ya start na stop. Upstream inaonya kuwa start kwenye container iliyoundwa kwa mipangilio tofauti huacha mtandao katika hali isiyo thabiti. Ikiwa unataka stack irejee baada ya reboot, restart: unless-stopped tayari inashughulikia hilo, na tabia ya boot ya huduma za compose inaelezea kile sera hiyo inachoahidi na kisichoahidi.

Web UI husikiliza kwenye TCP 51821. Unapoitembelea kwa mara ya kwanza, inaonyesha ukurasa wa usanidi ambapo utaunda akaunti ya msimamizi na kuthibitisha anwani ya host ambayo wateja watatumia kufikia seva. Anwani hiyo ya host huwekwa kwenye mstari wa Endpoint wa kila usanidi wa mteja, kwa hivyo lazima iwe IP ya umma au jina la DNS la VPS. Ikiwa ni sahihi, QR code unayompa mtumiaji wa simu itaelekeza mahali pasipoweza kufikika na handshake haitakamilika kamwe.

Jambo lingine kuhusu port hiyo: wg-easy 15 hukataa HTTP ya kawaida isipokuwa uweke INSECURE=true. Kuifikia kupitia HTTPS kwa kutumia cheti kisichoaminika, au kufanya TLS termination kwenye reverse proxy iliyo mbele yake, yote ni sawa. Kuifikia kupitia http:// kwa kutumia mipangilio chaguo-msingi haikubaliki.

Usichapishe port ya UI kwenye mtandao wa umma

Faili la compose linachapisha 51821 kwenye kila interface. Hiyo ni ukurasa wa kuingia (login) kwa kifaa kinachoweza kuelekeza trafiki yako, na haipaswi kuwa wazi kwa ulimwengu. Kuchapisha port katika Docker huandika sheria kwenye chain ya DOCKER, ambayo hupitiwa kabla ya ufw, kwa hivyo sheria ya ufw ya kuzuia (deny) haitaifunga. Mtego huu unastahili kueleweka peke yake, na kwa nini ports zilizochapishwa na Docker hupuuza ufw inalielezea kikamilifu.

Suluhisho rahisi ni kufunga (bind) UI kwenye loopback na kuifikia kupitia SSH tunnel:

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

Kisha kutoka kwenye laptop yako:

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

Fungua http://127.0.0.1:51821 kwenye kivinjari cha laptop yako. Trafiki husimbwa kwa njia ya SSH, port haijibu mtu mwingine yeyote, na INSECURE=true iko salama hapa kwa sababu hatua ya HTTP ya kawaida haitoki kamwe kwenye interface ya loopback.

Fungua UDP 51820, na uhakiki firewalls zote mbili

WireGuard yenyewe inahitaji UDP 51820 iweze kufikika kutoka kwenye Internet. Docker huichapisha, lakini watoa huduma wengi huweka firewall ya mtandao tofauti mbele ya VPS ambayo Docker haijui chochote kuihusu. Fungua port hiyo katika maeneo yote mawili. Ikiwa unasimamia firewall ya host kwa kutumia ufw, sheria za msingi za ufw kwa VPS ni njia fupi zaidi kuliko kuandika nftables kwa mkono.

Thibitisha kuwa container inasikiliza kweli:

sudo ss -ulnp | grep 51820

Unapaswa kuona UDP socket inayotii maombi. Kutokuwepo kwa chochote kwenye mstari huo kunamaanisha kuwa container haikuwahi kuwasha interface, na sudo docker compose logs wg-easy itataja sababu yake.

Unda mteja na umchanganue kwenye simu

Katika UI, unda mteja na umpe jina utakalolitambua baadaye, kama vile kifaa anachomiliki. wg-easy hutenga anwani ya tunnel inayofuata iliyo wazi na kukutengenezea jozi ya funguo. Kila mstari wa mteja hutoa QR code na faili ya .conf inayoweza kupakuliwa.

Sakinisha programu rasmi ya WireGuard kwenye simu, chagua kuongeza tunnel kutoka kwa QR code, na uelekeze kamera kwenye kodi iliyo kwenye skrini yako. Tunnel itaonekana ikiwa na jina ulilochapa. Iwake, na mstari wa mteja kwenye UI utaanza kuonyesha vihesabio vya data na muda wa mwisho wa handshake. Simu ikiwa kwenye tunnel inaweza kufikia huduma ambazo hukuzichapisha kwenye Internet, na ndivyo simu inavyoweza kuendelea kupakia data kwenye seva ya picha unayojiendeshea kutoka popote bila seva hiyo kuwa na port yoyote iliyo wazi kwa ulimwengu. Mbinu hiyo hiyo inafanya kazi kwa media, na maktaba ya Jellyfin iliyoundwa upya kama duka la video la miaka ya 90 ni kitu kizuri kuvinjari ukiwa chumba cha hoteli huku ikibaki kuwa ya faragha kama ilivyokuwa kwenye LAN yako. Arifa hufanya kazi kinyume chake kwenye tunnel hiyo hiyo, kwa kuwa seva ya ntfy unayojiendeshea inaweza kusukuma ujumbe kwenye simu hiyo wakati wowote kazi ya backup inapofeli bila kujibu ombi lolote kutoka kwa Internet ya umma.

Mteja ambaye haonyeshi handshake baada ya kumwezesha haifikii seva hata kidogo. Hilo linaashiria tatizo la UDP 51820, aidha kwenye firewall ya mtoa huduma au kwenye anwani ya endpoint iliyowekwa kwenye usanidi. Mteja anayeonyesha handshake lakini Internet haifanyi kazi anaashiria tatizo la forwarding au DNS.

Kwenye desktop, pakua faili ya .conf na uiingize kwenye mteja wa WireGuard badala ya kuichapa upya. Private key iliyo kwenye faili hiyo hutengenezwa mara moja na kuonyeshwa mara moja. Ichukulie faili hiyo kama unavyochukulia SSH private key.

Wakati wa kuacha kutumia UI

wg-easy ni zana sahihi wakati wenza wako ni watu na simu. UI ni ya haraka kuliko kuhariri faili za usanidi, na kufuta simu iliyopotea huchukua mbofyo mmoja tu.

Utafikia mipaka yake pale unapotaka kitu ambacho UI haikipi. Site-to-site routing, ambapo AllowedIPs ya peer inashughulikia subnet nzima ya mbali badala ya anwani moja, ndiyo kikwazo cha kwanza cha kawaida. Split tunnels zenye sheria za routing kwa kila peer, au usanidi unaozalishwa na zana yako ya provisioning, ndivyo vinavyofuata. Katika hatua hiyo, usanidi wa kuandika kwa mkono si mgumu zaidi, ni tofauti tu, na mwongozo wa kawaida wa WireGuard unaonyesha tunnel ileile iliyojengwa kutoka wg0.conf. Ikiwa ungependa kuacha kuendesha control plane kabisa, WireGuard ikilinganishwa na Tailscale inashughulikia chaguo linalosimamiwa. Ikiwa hiyo ni biashara ya haki inategemea kile ambacho seva ya uratibu inaweza kufikia, na mfumo wa uaminifu wa Tailscale unastahili kusomwa kabla ya kuikabidhi mtandao wako. Gharama kwa kawaida ndiyo swali linalofuata, na kile ambacho mpango wa bure wa Tailscale kinashughulikia kinatosha kiasi kwamba kaya au timu ndogo haitalipia chochote. Baada ya hatua hiyo, malipo huhesabu watumiaji badala ya vifaa, ambayo ni aina tofauti ya bili kutoka kwa VPS unayolipa tayari, kwa hivyo gharama za Tailscale baada ya kuzidi mpango wa bure ndiyo namba ya kuangalia kabla ya kuhamisha timu. Tunnel kamili uliyojenga hivi punde ina mlinganisho wa moja kwa moja huko, kwa sababu kutangaza VPS kama Tailscale exit node hukupa njia ileile ya kutoka kupitia seva, iliyoidhinishwa katika admin console badala ya kuandikwa katika kila usanidi wa mteja. Kikwazo cha subnet kina mlinganisho pia, kwa sababu kutangaza mtandao mzima wa kibinafsi kutoka kwa VPS hukabidhi mtandao huo kwa kila kifaa katika tailnet bila kuhariri AllowedIPs kwa kila peer ambayo ilikufanya uache kutumia UI. Ikiwa unataka dashibodi hiyo na routing ya kiotomatiki ya mesh lakini si seva ya uratibu ya mtu mwingine, kuendesha seva yako ya NetBird kwenye VPS huweka control plane kwenye maunzi unayomiliki, kwa gharama ya usanidi wa DNS na TLS ambao wg-easy haikuwahi kukuuliza.

Ikiwa sintaksia ya compose hapo juu ndiyo ilikuwa sehemu isiyo ya kawaida badala ya sehemu ya WireGuard, misingi ya Docker Compose kwenye VPS inaelezea umbizo la faili na amri za kila siku.

FAQ

Kwa nini wg-easy inapuuza WG_HOST na PASSWORD_HASH yangu?

Vigezo hivyo ni vya wg-easy 14. Toleo la 15 limeandikwa upya, na watengenezaji wamehamisha karibu usanidi wote kwenye paneli ya utawala katika kiolesura cha wavuti (web UI). Kontena haisomi vigezo vyovyote kati ya hivyo, kwa hivyo inaanza kama kawaida na kukuomba uunde akaunti ya msimamizi wakati wa ziara ya kwanza. Weka anwani ya mwenyeji (host) inayotumiwa na wateja kwenye ukurasa huo wa usanidi badala yake.

Je, ninahitaji SYS_MODULE ikiwa kernel yangu tayari ina WireGuard?

Hapana. SYS_MODULE na mount ya /lib/modules zipo ili kontena iweze kupakia moduli wakati mwenyeji (host) haijafanya hivyo. Kwenye mwenyeji ambapo sudo modprobe wireguard tayari inafanikiwa, uwezo huo hautumiki. Kuiondoa ni hatua nzuri ya kuimarisha usalama, na NET_ADMIN bado inahitajika kwa vyovyote vile.

Mteja anaunganisha lakini hakuna intaneti. Nini kimeharibika?

Handshake inayofanyika bila trafiki karibu kila mara inamaanisha tatizo la forwarding. Thibitisha kuwa net.ipv4.ip_forward=1 na net.ipv4.conf.all.src_valid_mark=1 bado zipo kwenye faili ya compose, kwa sababu nakala iliyohaririwa kwa mkono mara nyingi huzipoteza. Ikiwa forwarding imewashwa, angalia seva ya DNS ambayo mteja amepokea. Handaki inayotuma trafiki yote kupitia VPN lakini ikielekeza kwenye seva ya DNS ambayo haiwezi tena kuifikia inaonekana kama muunganisho uliokufa kwenye kivinjari.

Ninawezaje kuhifadhi nakala (backup) ya wateja wangu?

Kila kitu kipo kwenye volume yenye jina etc_wireguard, ndani ya faili ya wg0.json. Kiolesura cha mtumiaji pia kina kitufe cha backup kinachotoa data hiyo hiyo. Nakili faili hiyo mahali fulani nje ya seva kabla ya uboreshaji wowote. Kurejesha nakala hufanyika kwa kupakia faili hiyo wakati wa hatua ya usanidi kwenye kontena mpya.

Je, ninaweza kuendesha wg-easy nyuma ya reverse proxy?

Ndiyo. Weka proxy mbele ya TCP 51821, malizia TLS hapo, na uweke INSECURE=true kwenye kontena ili ikubali mawasiliano ya HTTP kutoka kwa proxy. Weka UDP 51820 ikiwa imechapishwa moja kwa moja, kwa sababu trafiki ya VPN ni UDP na haipiti kwenye HTTP proxy.