wg-easy Docker ile WireGuard web arayüzü kurulumu

Ne inşa ediliyor

wg-easy, tek bir Docker container olarak çalışan, web arayüzüne sahip WireGuard uygulamasıdır. WireGuard arayüzünü yönetir ve istemci oluşturmak için tarayıcı tabanlı bir arayüz ekler. Oluşturulan her istemci bir yapılandırma dosyası ve QR kodu alır. Böylece telefon, kamerası ekrana yöneltilerek VPN'e bağlanır.

Tünelin kendisi standart WireGuard kullanır. Paketleri kernel modülü ilettiği için aktarım hızı elle yapılan kurulumla aynıdır. Kazanılan özellik, SSH üzerinden yapılandırma dosyası düzenlemeden peer ekleme, devre dışı bırakma ve silme olanağıdır. Kaybedilen özellik ise bu yapılandırma üzerinde doğrudan denetimdir. Bu konu VPS üzerinde manuel WireGuard kurulumu bölümünde ele alınır.

Genel IPv4 adresine sahip bir KVM VPS, Compose plugin içeren Docker Engine ve root erişimi gerekir. OpenVZ veya LXC gibi host kernel'ini paylaşan container sanallaştırma çözümleri genellikle WireGuard modülünü yükleyemez. Bu nedenle container arayüzü etkinleştiremez.

15. sürüm ayarları ortamdan taşıdı

Bulunan kılavuzların çoğu, WG_HOST değerinin sunucu adresine ve PASSWORD_HASH değerinin yönetici parolasının bcrypt karmasına ayarlandığı wg-easy 14 için yazılmıştır. Bu değerlerin ikisi de ortam değişkeni olarak tanımlanıyordu. 15. sürüm yeniden yazılmıştır. Resmi geçiş notlarında, v15'in v14 ile aynı ortam değişkenlerini kullanmadığı ve bunların çoğunun web arayüzündeki yönetim paneline taşındığı açıkça belirtilir.

Bu nedenle WG_HOST ve PASSWORD_HASH artık herhangi bir işlem yapmaz. Eski bir compose dosyasını kopyalarsanız kapsayıcı başlar, bu satırları yok sayar ve ardından tarayıcıda bir yönetici hesabı oluşturmanızı ister. Bu bir hata değildir. Yeni kurulum akışı böyledir.

Temmuz 2026 itibarıyla sabitlenmesi gereken ana etiket 15 değeridir. latest kullanmak yerine ana sürümü sabitleyin. Çünkü ana sürüm yükseltmesi diskteki yapılandırma biçimini değiştirir ve temiz şekilde geri alınamaz.

Compose dosyası

Yığın için bir dizin oluşturun ve resmi Compose dosyasını bu dizine yazın. Bu, değiştirilmemiş upstream dosyasıdır.

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

İçerik aşağıdaki gibidir:

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, sunucu anahtarını ve oluşturduğunuz tüm istemcileri içeren adlandırılmış bir volume'dur. Bu volume'u yedekleyin. Aksi halde yeniden oluşturma işleminde tüm eşleriniz silinir. Bu dosyaları host dosya sisteminde görmek isterseniz bind mount kullanın. Ancak önce bind mount ile adlandırılmış volume arasındaki farkı okuyun; çünkü izinlerin işlenişi farklıdır.

NET_ADMIN, SYS_MODULE ve sysctl ayarlarına neden ihtiyaç duyulur?

Bir container'ın ağ yığınına varsayılan olarak erişmesine izin verilmez. Bu satırların her biri belirli bir engeli kaldırır.

NET_ADMIN, container'ın wg0 arayüzünü oluşturmasına, bu arayüze adres atamasına ve rotaları yazmasına izin verir. Bu izin olmadan container başlar, ancak arayüzü etkinleştirirken durur. Bunun nedeni ip link add wg0 type wireguard komutunun Operation not permitted döndürmesidir.

SYS_MODULE ile salt okunur /lib/modules bağlaması, host bu modülü henüz yüklememişse container'ın WireGuard kernel modülünü yüklemesine izin verir. Modül image'ın içinde değil, host kernel'inde bulunur. Bu nedenle host dizininin görünür olması gerekir. Modern bir kernel'de modül genellikle yerleşik olarak bulunur. Host üzerinde sudo modprobe wireguard && echo ok komutunu kullanarak bunu doğrulayabilirsiniz.

net.ipv4.ip_forward=1, kernel'in doğrudan bu makineyi hedeflemeyen paketleri iletmesini sağlar. Bu ayar olmadan istemci bağlanır ve handshake başarılı olur. Ancak internet üzerindeki her paketin atılması nedeniyle ping 1.1.1.1 zaman aşımına uğrar. Bu sırada VPN bağlı görünür.

net.ipv4.conf.all.src_valid_mark=1, kullanıcıları şaşırtan ayardır. WireGuard, kendi giden paketlerini tünelin içine yeniden yönlendirilmemeleri için işaretler. Katı reverse path filtering, kaynak adresi beklenen rotayla eşleşmeyen bir paket görür ve paketi düşürür. Bu sysctl, kernel'e işaretlenmiş paketleri kabul etmesini söyler. Böylece full tunnel kendi bağlantısını bozmaz.

Başlatın ve yönetici hesabını oluşturun

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

docker compose up ve docker compose down kullanılmalıdır; start ve stop kullanılmamalıdır. Upstream, farklı ayarlarla oluşturulmuş bir container üzerinde start çalıştırıldığında ağın tutarsız bir duruma geldiği konusunda uyarır. Yeniden başlatma sonrasında stack'in tekrar çalışmasını istiyorsanız restart: unless-stopped bunu zaten kapsar. compose servislerinin başlatma davranışı bu politikanın neyi garanti ettiğini ve neyi garanti etmediğini açıklar.

Web UI, TCP 51821 üzerinde dinler. İlk ziyaret sırasında, yönetici hesabının oluşturulduğu ve istemcilerin sunucuya erişmek için kullanacağı host adresinin onaylandığı bir kurulum sayfası görüntülenir. Bu host adresi her istemci yapılandırmasındaki Endpoint satırına eklenir. Bu nedenle adres, VPS'in genel IP adresi veya DNS adı olmalıdır. Adres yanlışsa telefona verilen QR kodu erişilemeyen bir konuma yönlendirir ve handshake tamamlanmaz.

Bu portla ilgili bir nokta daha vardır: wg-easy 15, INSECURE=true ayarlanmadığı sürece düz HTTP bağlantılarını reddeder. Güvenilmeyen bir sertifikayla HTTPS üzerinden erişim veya önündeki bir reverse proxy üzerinde TLS sonlandırılması uygundur. Varsayılan ayarlarla http:// üzerinden erişim uygun değildir.

UI bağlantı noktasını internete açmayın

Compose dosyası, 51821 bağlantı noktasını tüm arayüzlerde yayımlar. Bu, trafiğinizi yönlendirebilen bir sistemin oturum açma sayfasıdır ve herkese açık olmamalıdır. Docker'da bir bağlantı noktası yayımlandığında DOCKER zincirine kurallar yazılır. Bu zincir ufw'den önce değerlendirilir. Bu nedenle bir ufw deny kuralı bağlantı noktasını kapatmaz. Bu tuzağı ayrıca anlamak gerekir. Docker tarafından yayımlanan bağlantı noktalarının ufw kurallarını neden yok saydığı konusu bunu ayrıntılı olarak açıklar.

Basit çözüm, UI'yi loopback'e bağlamak ve ona bir SSH tüneli üzerinden erişmektir:

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

Ardından dizüstü bilgisayarınızdan:

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

Dizüstü bilgisayarınızın tarayıcısında http://127.0.0.1:51821 adresini açın. Trafik SSH tarafından şifrelenir. Bağlantı noktası başka hiçbir istemciye yanıt vermez. Düz HTTP bağlantısı loopback arayüzünden dışarı çıkmadığı için INSECURE=true burada güvenlidir.

UDP 51820 portunu açın ve her iki güvenlik duvarını da kontrol edin

WireGuard, UDP 51820 portuna internetten erişilebilmesini gerektirir. Docker bu portu yayımlar, ancak birçok sağlayıcı VPS'in önünde Docker'ın bilgi sahibi olmadığı ayrı bir ağ güvenlik duvarı bulundurur. Portu her iki yerde de açın. Ana makinenin güvenlik duvarını ufw ile yönetiyorsanız, VPS için temel ufw kuralları, nftables kurallarını elle yazmaktan daha kısa bir yoldur.

Container'ın gerçekten dinleme yaptığını kontrol edin:

sudo ss -ulnp | grep 51820

Dinleme yapan bir UDP soketi görmelisiniz. Bu satırda hiçbir çıktı olmaması, container'ın arayüzü başlatamadığı anlamına gelir; sudo docker compose logs wg-easy nedeni belirtir.

İstemci oluşturun ve telefonda tarayın

Arayüzde bir istemci oluşturun ve daha sonra tanıyabileceğiniz bir ad verin. Örneğin, istemcinin ait olduğu cihazın adını kullanın. wg-easy bir sonraki boş tünel adresini ayırır ve anahtar çiftini sizin için oluşturur. Her istemci satırında bir QR kodu ve indirilebilir bir .conf dosyası bulunur.

Telefona resmi WireGuard uygulamasını yükleyin. QR kodundan tünel ekleme seçeneğini belirleyin ve kamerayı ekranınızdaki koda doğrultun. Tünel, girdiğiniz adla görünür. Tüneli etkinleştirin. Ardından arayüzdeki istemci satırında aktarım sayaçları ve son el sıkışma zamanı görüntülenmeye başlar.

Etkinleştirdikten sonra el sıkışması görünmeyen bir istemci sunucuya hiç ulaşamıyor demektir. Sorun, sağlayıcının güvenlik duvarındaki veya yapılandırmaya eklenmiş endpoint adresindeki UDP 51820 ile ilgilidir. El sıkışması görünen ancak internet bağlantısı çalışmayan bir istemcide sorun yönlendirme veya DNS kaynaklıdır.

Masaüstünde .conf dosyasını indirin ve yeniden yazmak yerine WireGuard istemcisine aktarın. Bu dosyadaki özel anahtar bir kez oluşturulur ve yalnızca bir kez gösterilir. Dosyayı bir SSH özel anahtarını koruduğunuz şekilde koruyun.

UI'ın yetersiz kaldığı durumlar

wg-easy, eşleriniz insanlara ve telefonlara ait olduğu sürece uygun araçtır. UI, yapılandırma dosyalarını düzenlemekten daha hızlıdır. Kaybolan bir telefonun erişimini iptal etmek tek tıklamayla yapılır.

UI'ın modellemediği bir özellik gerektiğinde sınırlarına ulaşırsınız. Bir eşin AllowedIPs değerinin tek bir adres yerine uzak bir alt ağın tamamını kapsadığı siteden siteye yönlendirme, genellikle karşılaşılan ilk engeldir. Eş başına yönlendirme kurallarına sahip bölünmüş tüneller veya hazırlama aracınız tarafından oluşturulan bir yapılandırma sonraki adımdır. Bu noktada elle yazılan kurulum daha zor değildir; yalnızca farklıdır. düz WireGuard kılavuzu, aynı tünelin wg0.conf kullanılarak nasıl oluşturulduğunu gösterir. Denetim düzlemini çalıştırmayı tamamen bırakmak isteniyorsa WireGuard ile Tailscale karşılaştırması yönetilen seçeneği açıklar.

Yukarıdaki compose söz dizimi, WireGuard bölümünden daha yabancı geldiyse VPS üzerinde Docker Compose temelleri dosya biçimini ve günlük komutları açıklar.

FAQ

wg-easy neden WG_HOST ve PASSWORD_HASH değişkenlerini yok sayıyor?

Bu değişkenler wg-easy 14 sürümüne aittir. Sürüm 15 yeniden yazılmıştır ve upstream, yapılandırmanın neredeyse tamamını web arayüzündeki yönetim paneline taşımıştır. Container her iki değişkeni de okumaz. Bu nedenle normal şekilde başlar ve ilk ziyarette bir yönetici hesabı oluşturmanızı ister. İstemciye sunulacak host adresini bunun yerine bu kurulum sayfasında ayarlayın.

Kernel'de WireGuard zaten varsa SYS_MODULE gerekir mi?

Hayır. SYS_MODULE ve /lib/modules mount tanımları, host üzerinde modül bulunmadığında container'ın modülü yükleyebilmesi için vardır. sudo modprobe wireguard komutunun host üzerinde zaten başarıyla çalıştığı durumda bu yetenek kullanılmaz. Bunları kaldırmak makul bir hardening adımıdır. Ancak NET_ADMIN her durumda gereklidir.

İstemci bağlanıyor ancak internet yok. Sorun nedir?

Trafik olmayan bir handshake neredeyse her zaman forwarding sorunu olduğunu gösterir. net.ipv4.ip_forward=1 ve net.ipv4.conf.all.src_valid_mark=1 tanımlarının compose dosyasında hâlâ bulunduğunu doğrulayın. Elle düzenlenmiş bir kopyada bu tanımlar sıklıkla kaybolur. Forwarding açıksa istemcinin aldığı DNS sunucusunu kontrol edin. Tüm trafiği VPN üzerinden gönderen ancak artık erişemediği bir DNS sunucusunu kullanan tünel, tarayıcıda bağlantı tamamen çalışmıyormuş gibi görünür.

İstemcilerimi nasıl yedekleyebilirim?

Tüm veriler etc_wireguard adlı volume içinde, wg0.json dosyasında tutulur. UI'da aynı verileri dışa aktaran bir yedekleme düğmesi de vardır. Herhangi bir yükseltmeden önce bu dosyayı sunucu dışında bir konuma kopyalayın. Geri yükleme, yeni bir container ile kurulum adımı sırasında dosyanın yüklenmesiyle yapılır.

wg-easy reverse proxy arkasında çalıştırılabilir mi?

Evet. Proxy'yi TCP 51821'in önüne yerleştirin, TLS sonlandırmasını orada yapın ve proxy'den gelen düz HTTP bağlantısını kabul etmesi için container üzerinde INSECURE=true ayarını yapın. UDP 51820'yi doğrudan yayınlanmış olarak bırakın. VPN trafiği UDP kullanır ve bir HTTP proxy üzerinden geçmez.