Jinsi ya kusakinisha wg-easy na Docker kwa VPN

Unachojenga

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

Tunnel yenyewe ni WireGuard ya kawaida. Kernel module ndiyo inayohamisha pakiti, kwa hivyo kasi ya upitishaji data (throughput) ni sawa na usanidi uliotengenezwa kwa mikono. Unachopata ni usimamizi wa maisha ya 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 seva ya Linux unayoweza kuisimamia, kama vile KVM VPS, yenye anwani ya IP ya umma au domain name inayoelekeza huko, CPU ya x86_64 au arm64, Docker Engine yenye Compose plugin, na ufikiaji wa root. Uboreshaji wa container (container virtualisation) unaoshiriki kernel ya seva, kama vile OpenVZ au LXC, mara nyingi hauwezi kupakia module ya WireGuard, na container itashindwa kuwasha interface hiyo.

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 hash ya bcrypt 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 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. Ni mtiririko mpya wa usanidi.

Kufikia Oktoba 2026, tag kuu ya kutumia ni 15. Weka toleo kuu badala ya kutumia latest, kwa sababu upgrade kuu hubadilisha muundo wa usanidi kwenye diski na haitarudi nyuma kwa usalama. Hatua ya kwenda 15 ilibadilisha faili ya JSON ya v14 na database ya SQLite.

Faili la compose

Tengeneza saraka (directory) kwa ajili ya stack hii na uandike faili rasmi la compose ndani yake. Hili ni faili la asili kutoka kwa msanidi, likiwa limeondolewa mistari ya hiari iliyokuwa na maoni (commented-out).

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 volume yenye jina inayohifadhi ufunguo wa seva na kila mteja unayemuunda, yote yakihifadhiwa kwenye database ya SQLite wg-easy.db. Hifadhi nakala (backup) ya volume hiyo, la sivyo ujenzi mpya utafuta wenza wako wote (peers). 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 (permissions) 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, si start na stop. start huanzisha upya tu kontena zilizopo, kwa hivyo mabadiliko yoyote uliyofanya kwenye faili ya compose, ikiwemo mipangilio ya mtandao na sysctl, hayatatekelezwa, wakati up huunda upya chochote kilichobadilika. Ikiwa unataka stack irudi baada ya reboot, restart: unless-stopped tayari inashughulikia hilo, na tabia ya huduma za compose wakati wa boot inaeleza kile sera hiyo inachofanya na isichoweza kuahidi.

Kiolesura cha wavuti (web UI) husikiliza kwenye TCP 51821. Unapotembelea kwa mara ya kwanza, inaonyesha ukurasa wa usanidi ambapo unaunda 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 pasipofikika na handshake haitakamilika kamwe.

Jambo moja zaidi kuhusu port hiyo: wg-easy haitoi TLS yenyewe, na haikatai HTTP ya kawaida. Kupitia http://, UI bado hupakia na kuonyesha bango la onyo. Kile ambacho mabadiliko ya msingi hufanya ni kubadilisha session cookie, ambayo hubeba flag ya Secure, kwa hivyo kivinjari kinachofikia UI kupitia HTTP ya kawaida kwenye anwani ya umma huikataa na login haitadumu. INSECURE=true huondoa flag hiyo na haifanyi kitu kingine chochote. Kuweka reverse proxy mbele inayomalizia TLS, hata kwa cheti kilichojitolea (self-signed certificate), hakuhitaji mabadiliko yoyote kwenye wg-easy.

Usichapishe port ya UI kwenye Internet

Faili la compose huchapisha 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 hutathminiwa kabla ya ufw, kwa hivyo sheria ya ufw deny haifungi port hiyo. 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 fiche (encrypted) na SSH na port hiyo haijibu mtu mwingine yeyote. INSECURE=true huondoa tu alama ya Secure kutoka kwenye session cookie ili kivinjari kihifadhi login yako kwenye anwani hii ya plain HTTP, na hilo ni salama hapa kwa sababu hatua ya plain HTTP 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 haikitoi. Site-to-site routing, ambapo AllowedIPs ya peer inashughulikia subnet nzima ya mbali badala ya anwani moja, ndiyo kikwazo cha kawaida cha kwanza. 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 kabisa kuendesha control plane, WireGuard ikilinganishwa na Tailscale inashughulikia chaguo la huduma inayodhibitiwa. 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 ni hadi watumiaji sita bila gharama, kwa matumizi yasiyo ya kibiashara pekee, kwa hivyo kaya hulipa chochote wakati timu ndogo ya biashara haistahiki hata kama ina watu wachache. 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 mara unapozidi mpango wa bure ndiyo namba ya kuangalia kabla ya kuhamisha timu. Tunnel kamili uliyojenga hivi punde ina mbadala 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 mbadala pia, kwa sababu kutangaza mtandao mzima wa kibinafsi kutoka kwa VPS huupa mtandao huo kila kifaa kilicho kwenye tailnet bila kuhariri AllowedIPs kwa kila peer ambayo ilikufanya uache kutumia UI. Ikiwa unataka dashibodi hiyo na mesh routing ya kiotomatiki 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 syntax ya compose hapo juu ndiyo ilikuwa sehemu isiyo ya kawaida badala ya sehemu ya WireGuard, misingi ya Docker Compose kwenye VPS inaelezea muundo wa 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 ni andiko jipya, na watengenezaji wamehamishia usanidi karibu wote kwenye paneli ya utawala katika web UI. Kontena haisomi vigezo hivyo, kwa hivyo huanza kama kawaida na kukuomba uunde akaunti ya msimamizi unapoitembelea kwa mara ya kwanza. Weka anwani ya 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 host haijafanya hivyo. Kwenye host ambapo sudo modprobe wireguard inafanikiwa, uwezo huo hautumiki. Kuiondoa ni hatua nzuri ya kuimarisha usalama, na NET_ADMIN bado inahitajika kwa vyovyote vile.

Mteja anaunganishwa lakini hakuna intaneti. Nini kimeharibika?

Handshake bila trafiki karibu kila mara inamaanisha forwarding. Thibitisha 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. Tunnel inayotuma trafiki yote kupitia VPN lakini ikielekeza kwenye seva ya DNS ambayo haiwezi kuifikia tena inaonekana kama muunganisho uliokufa kwenye kivinjari.

Ninawezaje kuhifadhi nakala (backup) za wateja wangu?

Kila kitu kipo kwenye volume yenye jina la etc_wireguard. Katika toleo la 15, hiyo inamaanisha hifadhidata ya SQLite iliyopo /etc/wireguard/wg-easy.db ndani ya kontena. Nyaraka za v15 hazielezei kipengele cha backup au export, kwa hivyo hifadhi volume yenyewe: endesha docker compose down, nakili yaliyomo kwenye volume hiyo nje ya seva, kisha uwashe tena stack kwa docker compose up -d. Fanya hivi kabla ya upgrade yoyote. Faili ya wg0.json inayotajwa na miongozo ya zamani ni ya wg-easy 14. Ndiyo inayotolewa na kitufe cha backup cha v14, na katika v15 matumizi yake pekee ni kama faili unayopakia kwenye setup wizard unapohamia kutoka usakinishaji wa zamani.

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

Ndiyo. Weka proxy mbele ya port ya web UI, malizia TLS hapo, na uache INSECURE bila kuwekwa. Kontena inakubali HTTP hop ya kawaida kutoka kwa proxy kama ilivyo, na mifano rasmi ya Caddy na Traefik haiweki kigezo chochote cha INSECURE. Kwa kuwa kivinjari kinazungumza HTTPS na proxy, unataka session cookie idumishe alama yake ya Secure, ambayo ndiyo kitu pekee ambacho INSECURE=true huondoa. Weka UDP 51820 ikiwa imechapishwa moja kwa moja, kwa sababu trafiki ya VPN ni UDP na haipiti kwenye HTTP proxy.