Traefik v3, Let’s Encrypt ile Docker reverse proxy olarak nasıl çalıştırılır

Traefik, konteynerler için tasarlanmış bir reverse proxy'dir. Her siteyi listeleyen bir yapılandırma dosyası yerine Docker'ı izler ve konteynerlerinizdeki etiketleri (label) okur: doğru etiketlere sahip bir konteyner bir rota, Let's Encrypt'ten bir HTTPS sertifikası ve trafik alır; konteyner durduğunda rota da kaybolur. Bu rehber Traefik v3'ü Linux sunucuda Docker Compose ile çalıştırır, HTTP'yi HTTPS'e yönlendirir, sertifikaları HTTP doğrulamasıyla alır, örnek bir uygulamayı etiketlerle yayınlar, diğer rehberlerdeki uygulamaları nasıl bağlayacağınızı gösterir, isteğe bağlı olarak paneli korur ve Docker soketi riskini, logları, yedekleri ve güncellemeleri açıklar.

Adım 1 — Paylaşılan proxy ağını oluşturun

Traefik uygulamalarınıza onlarla paylaştığı bir Docker ağı üzerinden ulaşır. Bu ağı bir kez oluşturun; Traefik'in yayınlaması gereken her uygulama ona katılır:

docker network create proxy
docker network ls

Adım 2 — Traefik projesini oluşturun

Proje klasörünü ve sertifika deposu için bir klasör oluşturun:

sudo mkdir -p /opt/traefik
sudo chown $USER:$USER /opt/traefik
cd /opt/traefik
mkdir letsencrypt

Let's Encrypt hesabınızın e-posta adresini .env dosyasına yazın:

# /opt/traefik/.env
ACME_EMAIL[email protected]

chmod 600 /opt/traefik/.env

/opt/traefik/compose.yaml dosyasını oluşturun. Güncel ana sürüm Traefik v3'tür; v3.7 etiketi 3.7 yama sürümlerini izler:

services:
  traefik:
    image: traefik:v3.7
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--providers.docker.network=proxy"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--entrypoints.web.http.redirections.entrypoint.permanent=true"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.le.acme.email=${ACME_EMAIL:?set ACME_EMAIL in .env}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--log.level=INFO"
      - "--accesslog=true"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - proxy

networks:
  proxy:
    name: proxy
    external: true

Bayrakların görevleri:

• Docker sağlayıcısı — providers.docker, Traefik'in konteyner etiketlerini okumasını sağlar. exposedbydefault=false, traefik.enable=true etiketi olmayan konteynerlerin yok sayılması demektir; böylece hiçbir şey yanlışlıkla yayınlanmaz. providers.docker.network=proxy, bir konteyner birden fazla ağdaysa Traefik'e hangi ağı kullanacağını söyler.
• Giriş noktaları — web 80 numaralı portta dinler ve her isteği kalıcı olarak 443 numaralı porttaki websecure noktasına yönlendirir.
• Sertifika çözümleyici — le, web giriş noktası üzerinde HTTP-01 doğrulamasıyla Let's Encrypt'ten sertifika ister ve bunları ana makinedeki ./letsencrypt klasörüne karşılık gelen /letsencrypt/acme.json dosyasında saklar.
• Portlar — internete port yayınlayan tek konteyner Traefik'tir; 80 ve 443 numaralı portlarda.

Adım 3 — Traefik'i başlatın ve logları okuyun

docker compose up -d
docker compose ps
docker compose logs -f traefik

docker compose ps konteyneri 0.0.0.0:80->80/tcp ve 0.0.0.0:443->443/tcp ile çalışır durumda göstermelidir. Log, yapılandırmanın yüklendiğini ve Docker sağlayıcısının bağlandığını gösterir. Log izlemeyi Ctrl+C ile bırakın. Giriş noktalarını sunucudan test edin:

curl -I http://203.0.113.10
curl -kI https://203.0.113.10

HTTP isteği HTTPS'e kalıcı bir yönlendirme döndürür. HTTPS isteği (henüz gerçek bir sertifika olmadığı için -k ile) 404 döndürür; bu, hiçbir rota eşleşmediğinde Traefik'in verdiği yanıttır. Bir uygulama ekleyene kadar bu beklenen durumdur.

Adım 4 — Güvenlik duvarında web trafiğine izin verin

ufw'de SSH, HTTP ve HTTPS'e izin verin (Debian'da önce sudo apt install ufw ile kurun):

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Docker belgelerine göre yayınlanan konteyner portlarının ufw'yi atladığını unutmayın; çünkü Docker trafiği ufw kuralları uygulanmadan önce yönlendirir. Traefik'in 80 ve 443 numaralı portlarına bu kurallar olmadan da erişilebilir ve bir kural onları kapatamaz. Traefik arkasındaki uygulamaların hiç port yayınlamamasının nedeni budur.

Adım 5 — Bir uygulamayı etiketlerle yayınlayın

traefik/whoami imajı istek ayrıntılarını yazdıran küçük bir web sunucusudur; ilk test için idealdir. /opt/whoami/compose.yaml dosyasını oluşturun:

sudo mkdir -p /opt/whoami
sudo chown $USER:$USER /opt/whoami
cd /opt/whoami

services:
  whoami:
    image: traefik/whoami
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.example.com`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls.certresolver=le"
      - "traefik.http.services.whoami.loadbalancer.server.port=80"

networks:
  proxy:
    name: proxy
    external: true

Etiketler, ana makine adıyla eşleşen, HTTPS giriş noktasını dinleyen ve sertifikasını le çözümleyicisinden alan whoami adlı bir router ile trafiği konteynerin içindeki 80 numaralı porta gönderen bir service tanımlar. Başlatın ve test edin:

docker compose up -d
curl -I https://whoami.example.com
curl https://whoami.example.com

İlk sertifika isteği birkaç saniye sürer. Ardından HTTPS isteği HTTP/2 200 döndürür; ikinci komut, X-Forwarded-For ve X-Forwarded-Proto: https dahil, konteynerin gördüğü istek başlıklarını yazdırır. Sertifika gelmezse /opt/traefik içinde docker compose logs -f traefik ile izleyin.

Adım 6 — Diğer rehberlerdeki uygulamaları bağlayın

Bu kütüphanedeki uygulama rehberlerinin çoğu, uygulamayı Caddy veya Nginx için bir 127.0.0.1 portunda yayınlar. Traefik ile uygulamanın compose.yaml dosyasında üç değişiklik yapın: ports: kaydını kaldırın, proxy ağını ekleyin ve benzersiz bir router adı ile uygulamanın konteyner portunu içeren etiketleri ekleyin. Örneğin konteyneri içinde 5678 numaralı portta dinleyen bir uygulama için:

services:
  app:
    # imaj, ortam değişkenleri ve volume'lar uygulamanın rehberindeki gibi kalır
    networks:
      - default
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.myapp.rule=Host(`app.example.com`)"
      - "traefik.http.routers.myapp.entrypoints=websecure"
      - "traefik.http.routers.myapp.tls.certresolver=le"
      - "traefik.http.services.myapp.loadbalancer.server.port=5678"

networks:
  proxy:
    name: proxy
    external: true

default ağını da listeleyin: bir servis ağlarını adıyla belirttiğinde Compose onu artık projenin varsayılan ağına bağlamaz ve uygulama kendi veritabanıyla bağlantısını kaybeder. proxy ağına ve etiketlere yalnızca web'e açılan servisin ihtiyacı vardır; veritabanları default ağında kalır. Router ve service adları sunucudaki tüm projelerde benzersiz olmalıdır. WebSocket bağlantıları Traefik üzerinden ek ayar olmadan çalışır.

Adım 7 — Paneli koruyun (isteğe bağlı)

API ve panel, siz açmadıkça kapalıdır. Paneli istiyorsanız onu kendi ana makine adında, basic authentication ile yayınlayın; paneli girişsiz açan api.insecure seçeneğini asla kullanmayın. Bir bcrypt parola hash'i üretin ve Compose'un onu değişken sanmaması için her $ işaretini ikiye katlayın:

sudo apt install apache2-utils
htpasswd -nB admin | sed -e 's/\$/\$\$/g'

Ardından /opt/traefik/compose.yaml içindeki traefik servisini düzenleyin. command listesinin sonuna yeni bir satır olarak - "--api.dashboard=true" ekleyin ve command, ports ve volumes ile aynı düzeyde bir labels: anahtarı ekleyin. htpasswd komutunun çıktısını son etikete yapıştırın:

services:
  traefik:
    # command, ports ve volumes Adım 2'deki gibi kalır
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`)"
      - "traefik.http.routers.dashboard.entrypoints=websecure"
      - "traefik.http.routers.dashboard.tls.certresolver=le"
      - "traefik.http.routers.dashboard.service=api@internal"
      - "traefik.http.routers.dashboard.middlewares=dashboard-auth"
      - "traefik.http.middlewares.dashboard-auth.basicauth.users=admin:$$2y$$05$$replace-with-your-hash"

docker compose up -d çalıştırın, traefik.example.com için bir DNS kaydı ekleyin ve https://traefik.example.com/dashboard/ adresini açın. Erişimi daha da sınırlamak için traefik.http.middlewares.dashboard-ip.ipallowlist.sourcerange=198.51.100.7/32 gibi bir IP izin listesi middleware'i ekleyin ve iki middleware'i virgülle ayırarak listeleyin.

Adım 8 — Docker soketi riskini anlayın

Traefik etiketleri Docker API üzerinden okur; /var/run/docker.sock bu yüzden bağlanır. Traefik belgeleri, Docker API'ye kısıtlamasız erişimin bir güvenlik sorunu olduğu konusunda uyarır: Traefik'i ele geçiren bir saldırgan Docker'ı ve onun üzerinden sunucuyu yönetebilir. :ro bayrağı bunu değiştirmez; yalnızca konteynerin soket dosyasını değiştirmesini engeller.

Riski katmanlar halinde azaltın:

• Traefik'i güncel bir v3 sürümünde tutun (güncelleme bölümüne bakın),
• no-new-privileges ayarını koruyun ve Traefik konteynerine başka yetki eklemeyin,
• daha güçlü yalıtım için Traefik belgelerinin andığı gibi bir socket proxy çalıştırın, ona yalnızca konteynerler için okuma isteklerine izin verin ve soketi bağlamak yerine Traefik'i --providers.docker.endpoint=tcp://socket-proxy:2375 ile ona yönlendirin.

Yedekleme ve geri yükleme

Tüm durum /opt/traefik içindedir: compose.yaml, .env ve sertifikalarınızla ACME hesabınızı içeren letsencrypt/acme.json. Uygulama projeleri kendi etiketlerini taşır; onları uygulamalarla birlikte yedekleyin. acme.json root'a ait ve 600 izinli olduğu için sudo kullanın:

sudo mkdir -p /opt/backups
sudo tar czf /opt/backups/traefik-$(date +%F).tar.gz -C /opt traefik

Docker kurulu yeni bir sunucuda geri yüklemek için ağı yeniden oluşturun, arşivi açın ve Traefik'i başlatın:

docker network create proxy
sudo tar xzf /opt/backups/traefik-2026-10-09.tar.gz -C /opt
cd /opt/traefik
docker compose up -d

Özel anahtarlar içerdiği için arşivi gizli tutun ve sunucunun dışına kopyalayın.

Traefik güncelleme

Önce Traefik'in GitHub sürümler sayfasındaki sürüm notlarını okuyun, yedek alın, ardından imajı çekip konteyneri yeniden oluşturun:

cd /opt/traefik
docker compose pull
docker compose up -d
docker compose logs --tail 50 traefik

v3.7 etiketi yama sürümlerini alır. Daha yeni bir ara sürüme geçmek için Traefik belgelerindeki geçiş notlarını okuduktan sonra etiketi değiştirin (örneğin sürümler sayfasında listelenen bir sonraki v3.x). Güncelleme sırasında uygulamalar çalışmaya devam eder; yalnızca proxy kısa bir süre yeniden başlar.

Sorun giderme

404 page not found

Traefik yanıt verdi, ancak hiçbir router eşleşmedi. Konteynerde traefik.enable=true etiketinin bulunduğunu (exposedbydefault=false nedeniyle zorunludur), Host kuralının istediğiniz ana makine adını birebir içerdiğini ve konteynerin çalıştığını ve proxy ağında olduğunu kontrol edin: docker network inspect proxy bağlı konteynerleri listeler.

Tarayıcı TRAEFIK DEFAULT CERT sertifikası için uyarı veriyor

Traefik bir Let's Encrypt sertifikası alamadı ve kendi yerleşik, kendinden imzalı sertifikasını sunuyor. ACME hatası için /opt/traefik içinde docker compose logs traefik çıktısını okuyun. Sık nedenler sunucuyu göstermeyen DNS kayıtları, çalışan IPv6 olmadan eklenmiş bir AAAA kaydı veya harici bir güvenlik duvarının engellediği 80 numaralı porttur. Tekrarlanan hatalar Let's Encrypt'in ana makine adı başına saatte 5 başarısız doğrulama sınırına sayılır.

permissions 644 for /letsencrypt/acme.json are too open, please use 600

Sertifika deposunun izni yanlış. sudo chmod 600 /opt/traefik/letsencrypt/acme.json ile düzeltin ve Traefik'i docker compose restart traefik ile yeniden başlatın.

Bad Gateway veya Gateway Timeout

Traefik router'ı eşleştirdi, ancak konteynere ulaşamıyor. Konteynerin proxy ağında olduğundan ve loadbalancer.server.port değerinin bir ana makine portu değil, uygulamanın konteynerin içinde dinlediği port olduğundan emin olun. Uygulama birden fazla ağdaysa providers.docker.network=proxy bayrağı veya traefik.docker.network=proxy etiketi Traefik'e hangisini kullanacağını söyler.

client version 1.24 is too old

Eski bir Traefik sürümü, güncel bir Docker Engine ile API sürümünü uzlaştıramıyor. Traefik 3.6.1 otomatik API sürümü uzlaştırmasını ekledi; yukarıda anlatıldığı gibi güncel bir v3 etiketine güncelleyin.

Bind for 0.0.0.0:80 failed: port is already allocated

Ana makinede Nginx, Apache veya Caddy gibi başka bir web sunucusu 80 ya da 443 numaralı portu zaten kullanıyor. sudo ss -tlpn 'sport = :80' ile bulun, ardından Traefik'i başlatmadan önce onu durdurup devre dışı bırakın.

Sonraki adımlar

• Burada kullanılan Compose özelliklerini Docker Compose temelleri rehberinde öğrenin.
• Stack'lerinizi Portainer ile bir web arayüzünden yönetin.
• Tıklamayla yönetilen bir proxy mi tercih edersiniz? Nginx Proxy Manager rehberine bakın.
• Konteyner iş yükleri için bir sunucuyu Docker hosting sayfasında bulun.
• Router'ları, middleware'leri ve DNS doğrulamasını Traefik belgelerinde keşfedin.