Docker ile wg-easy WireGuard Kurulumu ve Yapılandırması

Ne inşa ediyorsunuz

wg-easy, tek bir Docker container olarak çalışan, web arayüzüne sahip bir WireGuard uygulamasıdır. WireGuard arayüzünü sizin yerinize yönetir ve istemci oluşturmak için bir tarayıcı arayüzü ekler. Oluşturduğunuz her istemci için bir yapılandırma dosyası ve QR kodu üretilir; böylece bir telefon, kamerasını ekrana tutarak VPN'e bağlanabilir.

Tünelin kendisi standart WireGuard'dır. Paketleri kernel modülü taşıdığı için veri aktarım hızı, elle yapılan bir kurulumla aynıdır. Kazancınız istemci yaşam döngüsüdür: SSH üzerinden yapılandırma dosyası düzenlemek zorunda kalmadan eşleri (peers) ekleyebilir, devre dışı bırakabilir ve silebilirsiniz. Vazgeçtiğiniz şey ise, bir VPS üzerinde manuel WireGuard kurulumu konusunda ele alınan, yapılandırma üzerindeki doğrudan kontroldür.

Halka açık bir IPv4 adresi olan bir KVM VPS'e, Docker Engine ve Compose eklentisine ve root erişimine ihtiyacınız vardır. OpenVZ veya LXC gibi ana makine kernel'ını paylaşan container sanallaştırma yöntemleri genellikle WireGuard modülünü yükleyemez ve bu durumda container arayüzü ayağa kaldıramaz.

Sürüm 15 ayarları ortam değişkenlerinden çıkardı

Bulacağınız çoğu kılavuz, WG_HOST değişkenini sunucu adresinize, PASSWORD_HASH değişkenini ise yönetici parolasının bcrypt özetine (hash) ortam değişkeni olarak atadığınız wg-easy 14 sürümü için yazılmıştır. Sürüm 15 ise tamamen yeniden yazılmıştır. Resmi geçiş notları, v15 sürümünün v14 ile aynı ortam değişkenlerini kullanmadığını ve bunların çoğunun web arayüzündeki yönetici paneline taşındığını açıkça belirtmektedir.

Bu nedenle WG_HOST ve PASSWORD_HASH artık hiçbir işlev görmemektedir. Eski bir compose dosyasını kopyalarsanız, container başlar, bu satırları yok sayar ve ardından tarayıcı üzerinden bir yönetici hesabı oluşturmanızı ister. Bu bir hata değildir. Bu, yeni kurulum akışıdır.

Temmuz 2026 itibarıyla sabitlenmesi gereken ana etiket 15 şeklindedir. latest kullanmak yerine ana sürümü sabitleyin; çünkü ana sürüm yükseltmeleri disk üzerindeki yapılandırma biçimini değiştirir ve temiz bir şekilde geri alınamaz.

Compose dosyası

Stack için bir dizin oluşturun ve resmi compose dosyasını bu dizin içerisine yazın. Bu, üzerinde değişiklik yapılmamış 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

Dosya içeriği şu şekildedir:

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 her istemciyi barındıran adlandırılmış bir volume'dür (named volume). Bu volume'ü yedekleyin; aksi takdirde bir yeniden kurulum tüm eşlerinizi (peers) siler. Eğer bu dosyaları host dosya sisteminde görmeyi tercih ederseniz, bunu bir bind mount ile değiştirin. Ancak bunu yapmadan önce bind mount ve adlandırılmış volume'ler arasındaki fark konusunu okuyun, çünkü izinler farklı şekilde işler.

Neden NET_ADMIN, SYS_MODULE ve sysctl ayarları gereklidir

Bir container varsayılan olarak ağ yığınına müdahale edemez; bu satırların her biri belirli bir kısıtlamayı kaldırır.

NET_ADMIN, container'ın wg0 arayüzünü oluşturmasına, bir adres atamasına ve yönlendirme kuralları yazmasına olanak tanır. Bu yetki olmadan container başlar ancak arayüzü ayağa kaldırırken ip link add wg0 type wireguard, Operation not permitted hatası döndürdüğü için kapanır.

SYS_MODULE ve salt okunur /lib/modules bağlaması (mount), ana makinede yüklü değilse WireGuard çekirdek modülünün container tarafından yüklenmesini sağlar. Modül imajın içinde değil, ana makinenin çekirdeğinde bulunur; bu nedenle ana makine dizininin görünür olması gerekir. Modern çekirdeklerde modül genellikle yerleşik olarak gelir; bunu ana makinede sudo modprobe wireguard && echo ok komutu ile doğrulayabilirsiniz.

net.ipv4.ip_forward=1, çekirdeğin kendisine gönderilmeyen paketleri iletmesini (forward) sağlar. Bu ayar olmadan istemci bağlanır, el sıkışma başarılı olur ancak internete giden her paket düşürülür; bu yüzden VPN bağlı görünse de ping 1.1.1.1 zaman aşımına uğrar.

net.ipv4.conf.all.src_valid_mark=1 genellikle kullanıcıları şaşırtan ayardır. WireGuard, kendi giden paketlerini işaretler; böylece bu paketler tekrar tünele yönlendirilmez. Sıkı ters yol filtreleme (strict reverse path filtering), kaynak adresi beklenen rota ile eşleşmeyen bir paket gördüğünde onu düşürür. Bu sysctl ayarı, çekirdeğe işaretli paketleri kabul etmesini söyler; tam tünel yapısının kendi kendini bozmasını engelleyen mekanizma budur.

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

start ve stop yerine docker compose up ve docker compose down kullanın. Upstream, farklı ayarlarla oluşturulmuş bir container üzerinde start komutunun ağı tutarsız bir durumda bıraktığı konusunda uyarıda bulunmaktadır. Yeniden başlatma sonrasında yığının geri gelmesini istiyorsanız, restart: unless-stopped bunu zaten karşılamaktadır ve compose servislerinin önyükleme davranışı bu politikanın neyi vaat edip neyi etmediğini açıklamaktadır.

Web arayüzü TCP 51821 portunu dinler. İlk ziyarette, yönetici hesabını oluşturacağınız ve istemcilerin sunucuya ulaşmak için kullanacağı ana bilgisayar adresini onaylayacağınız bir kurulum sayfası görüntülenir. Bu ana bilgisayar adresi, her istemci yapılandırmasının Endpoint satırına yazılır; bu nedenle genel IP adresi veya VPS'in DNS adı olmalıdır. Adres yanlışsa, telefona verdiğiniz QR kodu ulaşılamaz bir yeri işaret eder ve el sıkışma (handshake) asla tamamlanmaz.

Bu portla ilgili bir husus daha: wg-easy 15, INSECURE=true ayarlanmadığı sürece düz HTTP bağlantılarını reddeder. Arayüze güvenilmeyen bir sertifika ile HTTPS üzerinden erişmek veya ön taraftaki bir reverse proxy üzerinde TLS termination yapmak uygundur. Varsayılan ayarlarla http:// üzerinden erişim sağlamak ise mümkün değildir.

UI portunu internete açmayın

Compose dosyası, 51821 numaralı portu tüm arayüzlerde yayınlar. Bu port, trafiğinizi yönlendirebilen bir kutunun giriş sayfasıdır ve dünyaya açık olmamalıdır. Docker'da bir port yayınlamak, DOCKER zincirine kurallar yazar; bu zincir ufw'den önce değerlendirildiği için bir ufw deny kuralı portu kapatmaz. Bu tuzak başlı başına anlaşılması gereken bir konudur ve Docker yayınlanan portlarının neden ufw'yi görmezden geldiği konusu bunu tüm detaylarıyla ele alır.

Basit çözüm, UI'ı loopback arayüzüne 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 şu komutu çalıştırın:

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

Dizüstü bilgisayarınızdaki tarayıcıda http://127.0.0.1:51821 adresini açın. Trafik SSH ile şifrelenir, port başka kimseye yanıt vermez ve düz HTTP geçişi asla loopback arayüzünden dışarı çıkmadığı için INSECURE=true burada güvendedir.

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

WireGuard'ın kendisi, internet üzerinden UDP 51820 portuna erişilebilmesini gerektirir. Docker bu portu yayınlar ancak birçok sağlayıcı, VPS'in önüne Docker'ın haberdar olmadığı ayrı bir ağ güvenlik duvarı yerleştirir. Portu her iki yerde de açın. Eğer ana makine güvenlik duvarını ufw ile yönetiyorsanız, bir VPS için temel ufw kuralları rehberi, nftables kurallarını elle yazmaktan daha kısa bir yoldur.

Konteynerin gerçekten dinleme yapıp yapmadığını kontrol edin:

sudo ss -ulnp | grep 51820

Bir dinleme yapan UDP soketi görmelisiniz. Bu satırda hiçbir şey görünmüyorsa, konteyner arayüzü hiç ayağa kaldırmamış demektir ve sudo docker compose logs wg-easy bunun nedenini belirtecektir.

Bir istemci oluşturun ve telefonda taratın

Arayüzde bir istemci oluşturun ve daha sonra tanıyabileceğiniz, örneğin ait olduğu cihaz gibi bir isim verin. wg-easy bir sonraki boş tünel adresini atar ve sizin için anahtar çiftini oluşturur. Her istemci satırı bir QR kodu ve indirilebilir bir .conf dosyası sunar.

Resmi WireGuard uygulamasını telefona yükleyin, QR kodundan tünel eklemeyi seçin ve kamerayı ekranınızdaki koda doğrultun. Tünel, yazdığınız isimle görünür. Tüneli açtığınızda, arayüzdeki istemci satırı transfer sayaçlarını ve son el sıkışma (handshake) zamanını göstermeye başlar. Bir telefon tünele bağlandığında, internete hiç açmadığınız servislere erişebilir; bu sayede bir telefon, sunucunun dış dünyaya tek bir portu bile açık olmadan her yerden kendi barındırdığınız bir fotoğraf sunucusuna veri yükleyebilir. Aynı yöntem medya için de geçerlidir; 90'ların video dükkanı gibi yeniden tasarlanmış bir Jellyfin kütüphanesi, yerel ağınızdaki kadar gizli kalırken bir otel odasından göz atması keyifli bir deneyim sunar. Uyarılar aynı tünel üzerinden ters yönde çalışır; kendi barındırdığınız bir ntfy sunucusu, bir yedekleme işi başarısız olduğu anda, genel internetten gelen bir isteği yanıtlamak zorunda kalmadan o telefona mesaj gönderebilir.

Etkinleştirdikten sonra el sıkışma göstermeyen bir istemci sunucuya hiç ulaşamıyor demektir. Bu durum, sağlayıcı güvenlik duvarındaki veya yapılandırmaya işlenmiş uç nokta adresindeki UDP 51820 portuna işaret eder. El sıkışma gösteren ancak internet bağlantısı çalışmayan bir istemci ise yönlendirme veya DNS sorununa işaret eder.

Masaüstünde .conf dosyasını indirin ve yeniden yazmak yerine WireGuard istemcisine içe aktarın. Bu dosyadaki özel anahtar bir kez oluşturulur ve bir kez gösterilir. Dosyaya, bir SSH özel anahtarına davrandığınız gibi davranın.

Arayüzün yetersiz kaldığı durumlar

wg-easy, kullanıcılarınız insanlar ve telefonlardan ibaret olduğu sürece doğru araçtır. Arayüz, yapılandırma dosyalarını düzenlemekten daha hızlıdır ve kaybolan bir telefonu sistemden çıkarmak tek bir tıklama ile gerçekleşir.

Arayüzün modellemediği bir özellik istediğinizde sınırlarına ulaşırsınız. Bir eşin (peer) AllowedIPs değerinin tek bir adres yerine tüm uzak alt ağı (subnet) kapsadığı "site-to-site" yönlendirme, genellikle karşılaşılan ilk engeldir. Eş bazlı yönlendirme kurallarına sahip "split tunnel" yapıları veya sağlama (provisioning) aracınız tarafından oluşturulan bir yapılandırma, bir sonraki aşamadır. Bu noktada elle yapılan kurulum daha zor değildir, sadece farklıdır; yalın WireGuard rehberi, aynı tünelin wg0.conf kullanılarak nasıl kurulacağını gösterir. Eğer kontrol düzlemini (control plane) tamamen çalıştırmayı bırakmak isterseniz, WireGuard ve Tailscale karşılaştırması yönetilen seçeneği ele alır. Bunun adil bir takas olup olmadığı, koordinasyon sunucusunun gerçekte nelere erişebileceğine bağlıdır; bu nedenle ağınızı teslim etmeden önce Tailscale güven modeli okunmalıdır. Maliyet genellikle bir sonraki sorudur ve Tailscale ücretsiz planının neleri kapsadığı, bir hane veya küçük bir ekip için hiçbir ücret ödemeden kullanım sağlamaya yeterlidir. Bu noktadan sonra faturalandırma cihaz yerine kullanıcı sayısını esas alır; bu, halihazırda ödediğiniz bir VPS'ten farklı bir fatura yapısıdır. Bu nedenle, bir ekibi taşımadan önce ücretsiz plan aşıldığında Tailscale maliyetleri kontrol edilmelidir. Az önce oluşturduğunuz tam tünelin (full tunnel) orada doğrudan bir karşılığı vardır; VPS'i Tailscale çıkış düğümü (exit node) olarak tanıtmak, her istemci yapılandırmasına yazmak yerine yönetici konsolundan onaylanan aynı yönlendirmeyi sunucu üzerinden sağlar. Alt ağ engeli için de bir karşılık mevcuttur; VPS üzerinden tüm özel ağı tanıtmak, sizi arayüzden uzaklaştıran eş bazlı AllowedIPs düzenlemelerine gerek kalmadan o ağı tailnet içindeki her cihaza sunar. Eğer o paneli ve otomatik mesh yönlendirmeyi istiyor ancak başkasının koordinasyon sunucusunu kullanmak istemiyorsanız, kendi NetBird sunucunuzu bir VPS üzerinde çalıştırmak, kontrol düzlemini kendi donanımınızda tutmanızı sağlar; ancak bunun bedeli, wg-easy'nin sizden hiç istemediği DNS ve TLS kurulumunu yapmaktır.

Eğer yukarıdaki compose sözdizimi WireGuard kısmından 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şkenlerimi yok sayıyor?

Bu değişkenler wg-easy 14 sürümüne aittir. 15. sürüm baştan yazılmıştır ve geliştiriciler yapılandırmanın neredeyse tamamını web arayüzündeki yönetim paneline taşımıştır. Container bu değişkenleri okumaz; bu nedenle normal şekilde başlar ve ilk ziyarette sizden bir yönetici hesabı oluşturmanızı ister. İstemciye yönelik ana bilgisayar adresini bu kurulum sayfasından ayarlayın.

Çekirdeğimde zaten WireGuard varsa SYS_MODULE gerekli mi?

Hayır. SYS_MODULE ve /lib/modules bağlamaları, ana bilgisayarda modül bulunmadığında container'ın bunu yükleyebilmesi için vardır. sudo modprobe wireguard komutunun başarıyla çalıştığı bir ana bilgisayarda bu yetenek kullanılmaz. Bunu kaldırmak makul bir güvenlik sıkılaştırma adımıdır; ancak NET_ADMIN her iki durumda da gereklidir.

İstemci bağlanıyor ancak internete çıkış yok. Sorun nedir?

El sıkışma gerçekleşmesine rağmen trafik akmıyorsa sorun neredeyse her zaman yönlendirmedir (forwarding). Elle düzenlenen kopyalarda genellikle silindiği için net.ipv4.ip_forward=1 ve net.ipv4.conf.all.src_valid_mark=1 ayarlarının compose dosyasında yer aldığını doğrulayın. Yönlendirme aktifse, istemcinin aldığı DNS sunucusunu kontrol edin. Tüm trafiği VPN üzerinden gönderen ancak artık erişemediği bir DNS sunucusuna işaret eden bir tünel, tarayıcıda bağlantı kopukluğu gibi görünür.

İstemcilerimin yedeğini nasıl alırım?

Her şey etc_wireguard adlı volume içerisinde, wg0.json dosyasında tutulur. Arayüzde aynı veriyi dışa aktaran bir yedekleme düğmesi de bulunur. Herhangi bir yükseltme işleminden önce bu dosyayı sunucu dışına kopyalayın. Geri yükleme işlemi, yeni bir container kurulumu sırasındaki yükleme adımıyla yapılır.

wg-easy'yi bir reverse proxy arkasında çalıştırabilir miyim?

Evet. Proxy'yi TCP 51821 portunun önüne koyun, TLS sonlandırmasını orada yapın ve proxy'den gelen düz HTTP trafiğini kabul etmesi için container üzerinde INSECURE=true ayarını yapın. UDP 51820 portunu doğrudan dışarıya açık tutun; çünkü VPN trafiği UDP tabanlıdır ve HTTP proxy üzerinden geçmez.