Nginx, Let’s Encrypt ve Certbot ile reverse proxy nasıl kurulur

Nginx, birçok yöneticinin zaten tanıdığı, hızlı ve yaygın kullanılan bir web sunucusudur. Reverse proxy olarak 80 ve 443 numaralı portlarda durur ve istekleri yerel portlarda dinleyen uygulamalara iletir; örneğin 127.0.0.1:8080 üzerinde yayınlanan bir Docker konteynerine. EFF'nin geliştirdiği Let's Encrypt istemcisi Certbot ücretsiz bir sertifika alır, Nginx yapılandırmasını bu sertifikayı kullanacak şekilde düzenler ve sertifikayı otomatik olarak yeniler. Bu rehber Nginx'i dağıtımınızın deposundan kurar, WebSocket desteği ve yaygın iletilen başlıklarla bir reverse proxy server bloğu yazar, Certbot snap ile HTTPS ekler, yenilemeyi doğrular; sağlamlaştırma, yedekleme, güncelleme ve sık görülen hataları ele alır.

Adım 1 — Nginx'i kurun

Bu rehber Ubuntu veya Debian'ın nginx paketini kullanır. Bu paket güvenlik düzeltmelerini dağıtımınızın güvenlik güncellemeleriyle (Ubuntu'da unattended-upgrades ile) alır, Certbot'un nginx eklentisinin iyi tanıdığı sites-available ve sites-enabled düzenini kullanır ve ufw uygulama profilleriyle gelir. Sürümler upstream'den eskidir (örneğin Ubuntu 24.04'te 1.24, Ubuntu 26.04'te 1.28), ancak bir reverse proxy'nin ihtiyaç duyduğu her özelliğe sahiptir.

sudo apt update
sudo apt install nginx
systemctl status nginx --no-pager
curl -I http://localhost

Servis kendiliğinden başlar ve curl, varsayılan karşılama sayfasından HTTP/1.1 200 OK döndürür.

Adım 2 — Güvenlik duvarını açın

Dağıtım paketi Nginx için ufw profilleri kurar. Nginx Full 80 ve 443 numaralı portları açar:

sudo ufw app list
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status verbose

Debian'da önce ufw'yi sudo apt install ufw ile kurun. ufw app list hiçbir Nginx profili göstermiyorsa bunun yerine 80/tcp ve 443/tcp portlarına izin verin. HTTPS çalıştıktan sonra da 80 numaralı portu açık tutun: Let's Encrypt her yenilemede HTTP-01 doğrulaması için bu portu kullanır.

Adım 3 — WebSocket yardımcı map'ini ekleyin

Birçok self-hosted uygulama canlı güncellemeler için WebSocket kullanır. Bunlara proxy yapmak için Nginx'in Upgrade başlığını iletmesi ve Connection başlığını yalnızca istemci yükseltme istediğinde upgrade yapması gerekir. http bağlamındaki bir map bunu tüm siteler için bir kez yapar. Ubuntu ve Debian'ın nginx.conf dosyası /etc/nginx/conf.d/ içindeki her dosyayı içerir; bu yüzden dosyayı orada oluşturun:

sudo nano /etc/nginx/conf.d/websocket-upgrade.conf

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Adım 4 — Uygulamanız için bir server bloğu oluşturun

Ana makine adıyla adlandırılmış bir yapılandırma dosyası oluşturun:

sudo nano /etc/nginx/sites-available/app.example.com

server {
    listen 80;
    listen [::]:80;
    server_name app.example.com;

    # uygulamanın kabul ettiği en büyük yükleme; Nginx varsayılanı 1m
    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 300s;
    }
}

Yönergelerin görevleri:

• server_name ana makine adıyla birebir eşleşmelidir; Certbot bloğu bulmak için onu kullanır.
• Yol içermeyen proxy_pass, istek URI'sini uygulamaya değiştirmeden iletir.
• proxy_http_version 1.1, yukarıda listelenen tüm dağıtım paketleri dahil 1.29.7'den eski Nginx sürümlerinde WebSocket için gereklidir. Daha yeni sürümler varsayılan olarak 1.1 kullanır.
• Host, 127.0.0.1 yerine özgün ana makine adını iletir. X-Forwarded-* ve X-Real-IP başlıkları uygulamaya ziyaretçinin adresini ve özgün isteğin HTTPS kullandığını bildirir.
• client_max_body_size yükleme sınırını yükseltir. 1 MB varsayılanıyla daha büyük yüklemeler 413 Request Entity Too Large hatasıyla başarısız olur.
• proxy_read_timeout, boşta kalan WebSocket ve long-polling bağlantılarını varsayılan 60 saniye yerine 5 dakika açık tutar.

Siteyi etkinleştirin, sözdizimini test edin ve yeniden yükleyin:

sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -I http://app.example.com

nginx -t çıktısında syntax is ok ve test is successful görünmelidir. curl isteği uygulamanızın yanıtını düz HTTP üzerinden döndürmelidir. Her ek uygulama için bu adımı yeni bir dosya, ana makine adı ve portla tekrarlayın.

Adım 5 — Certbot'u kurun

Certbot ekibi Certbot'un snap olarak kurulmasını önerir. Ubuntu Server snapd ile gelir. Debian'da önce snapd'yi kurun, ardından snap yollarının ayarlanması için oturumu kapatıp yeniden açın (veya sunucuyu yeniden başlatın):

sudo apt update
sudo apt install snapd

certbot komutunun snap'i çalıştırması için apt ile kurulmuş Certbot paketlerini kaldırın, ardından Certbot'u kurup komutu bağlayın:

sudo apt remove certbot
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/local/bin/certbot
certbot --version

Certbot hiç apt ile kurulmadıysa ilk komut yalnızca paketin kurulu olmadığını bildirir.

Adım 6 — nginx eklentisiyle sertifika alın

Ana makine adı için bir sertifika isteyin ve server bloğunu Certbot'un güncellemesine izin verin:

sudo certbot --nginx -d app.example.com

İlk çalıştırma bir e-posta adresi ve Let's Encrypt koşullarını kabul etmenizi ister. Certbot ardından alan adının denetiminin sizde olduğunu 80 numaralı port üzerinden kanıtlar, sertifikayı /etc/letsencrypt/live/app.example.com/ altına kaydeder, server bloğunuza listen 443 ssl satırını ve sertifika yollarını ekler ve tüm HTTP isteklerini HTTPS'e yönlendiren ayrı bir 80 numaralı port bloğu oluşturur. Birden fazla ana makine adını tek sertifikayla kapsamak için -d seçeneğini tekrarlayın; örneğin -d example.com -d www.example.com.

Sonucu doğrulayın:

sudo certbot certificates
curl -I http://app.example.com
curl -I https://app.example.com

certbot certificates alan adlarını, son kullanma tarihini ve dosya yollarını listeler. HTTP isteği HTTPS adresine 301 Moved Permanently döndürür, HTTPS isteği ise uygulamanızın yanıtını döndürür.

Adım 7 — Otomatik yenilemeyi kontrol edin

Certbot snap'i certbot renew komutunu düzenli olarak çalıştıran bir systemd zamanlayıcısı kurar. Her çalıştırma süresi dolmaya yaklaşan sertifikaları yeniler; Certbot 4.0'dan beri bu, ömrünün üçte birinden azı kalmış sertifikalar demektir. Zamanlayıcıyı kontrol edin ve Let's Encrypt staging ortamına karşı bir yenilemeyi deneyin:

systemctl list-timers | grep certbot
sudo certbot renew --dry-run

Deneme çalıştırması Congratulations, all simulated renewals succeeded ile biter. Sertifika nginx eklentisiyle kurulduğu için Certbot her gerçek yenilemeden sonra Nginx'i yeniden yükler.

Otomatik yenilemenin önemi her yıl artıyor. Let's Encrypt sertifikaları bugün 90 gün geçerlidir; Let's Encrypt Şubat 2027'den itibaren 64 günlük, Şubat 2028'den itibaren 45 günlük sertifikaları duyurmuştur. Ayrıca süre dolum hatırlatma e-postalarını Haziran 2025'te durdurmuştur; bu yüzden ara sıra sudo certbot certificates çıktısını kontrol edin veya harici bir sertifika izleme aracı kullanın.

Adım 8 — HTTPS sitesini sağlamlaştırın

Birkaç küçük değişiklik kurulumu daha sıkı hale getirir:

• Sürüm numarasını gizleyin. /etc/nginx/nginx.conf dosyasında http bloğundaki server_tokens off; satırının yorumunu kaldırın.
• HTTP/2'yi açın. Nginx 1.25.1 ve sonrasında (Ubuntu 26.04, Debian 13) HTTPS server bloğuna http2 on; ekleyin. Ubuntu 24.04 ve Debian 12'de bunun yerine Certbot'un yazdığı listen 443 ssl satırlarına (IPv4 ve IPv6) ssl sözcüğünden sonra http2 ekleyin. Sürümünüzü nginx -v ile kontrol edin.
• HSTS'i dikkatle değerlendirin. HSTS, tarayıcılara bu ana makine adı için belirli bir süre yalnızca HTTPS kullanmalarını söyler. HTTPS server bloğunda kısa bir süreyle başlayın ve süreyi ancak her şey çalıştıktan sonra artırın:

add_header Strict-Transport-Security "max-age=300" always;

Her değişiklikten sonra sudo nginx -t ve sudo systemctl reload nginx çalıştırın.

Yedekleme ve geri yükleme

Kurulumun tamamı iki klasörde durur:

• /etc/nginx/ — nginx.conf, conf.d/ ve tüm server blokları,
• /etc/letsencrypt/ — sertifikalar, özel anahtarlar, ACME hesabı ve yenileme yapılandırması.

/etc/letsencrypt/live/ içindeki sembolik bağlantıları koruyarak ikisini birlikte arşivleyin:

sudo mkdir -p /opt/backups
sudo tar czf /opt/backups/nginx-letsencrypt-$(date +%F).tar.gz /etc/nginx /etc/letsencrypt

Yeni bir sunucuda geri yüklemek için Nginx'i ve Certbot'u Adım 1 ve 5'teki gibi kurun, arşivi açın, ardından yapılandırmayı ve yenilemeyi test edin:

sudo tar xzf /opt/backups/nginx-letsencrypt-2026-10-09.tar.gz -C /
sudo nginx -t
sudo systemctl reload nginx
sudo certbot renew --dry-run

Arşiv özel anahtarlar içerir; kısıtlı izinlerle saklayın ve sunucunun dışına kopyalayın.

Nginx ve Certbot güncelleme

Nginx güncellemeleri normal sistem güncellemelerinizle gelir. Dağıtım paketinin değişiklik günlüğünde yapılandırmanızı etkileyen bir şey olup olmadığına bakın, ardından yükseltin:

sudo apt update
sudo apt upgrade
nginx -v
sudo nginx -t

Snap'ler arka planda kendiliğinden güncellenir; böylece Certbot güncel kalır. Kurulu sürümü kontrol edin ve gerekirse güncellemeyi zorlayın:

snap list certbot
sudo snap refresh certbot

Sorun giderme

502 Bad Gateway

Nginx uygulamaya ulaşamıyor. /var/log/nginx/error.log içinde connect() failed (111: Connection refused) while connecting to upstream satırını arayın, ardından uygulamayı curl -I http://127.0.0.1:8080 ile doğrudan test edin. Konteynerin veya servisin çalıştığını ve proxy_pass içindeki portun yayınlanan portla eşleştiğini kontrol edin.

413 Request Entity Too Large

Yükleme client_max_body_size değerinden büyük. Server bloğundaki değeri örneğin 100m olarak yükseltin, ardından Nginx'i test edip yeniden yükleyin. Bazı uygulamaların kendi yükleme sınırı da vardır.

WebSocket bağlantıları kurulamıyor veya yaklaşık bir dakika sonra kopuyor

Adım 3'teki map tanımının var olduğunu, location bloğunun hem Upgrade hem Connection başlıklarını gönderdiğini ve proxy_http_version 1.1 ayarının yapıldığını kontrol edin. Boşta kalan bağlantılar varsayılan olarak 60 saniye olan proxy_read_timeout süresinden sonra kapatılır; bu süreyi artırın veya uygulamanın WebSocket ping göndermesini sağlayın.

Could not automatically find a matching server block

Certbot, server_name değeri -d ile verilen ana makine adıyla eşleşen bir server bloğu bulamadı. server_name satırını düzeltin, sitenin sites-enabled içine bağlandığından emin olun, sudo nginx -t ve sudo systemctl reload nginx çalıştırın, ardından Certbot'u yeniden çalıştırın.

Certbot Timeout during connect veya bir DNS sorunuyla başarısız oluyor

Let's Encrypt internetten http://app.example.com/.well-known/acme-challenge/ adresine ulaşamadı. A ve AAAA kayıtlarını dig +short ile, ufw kurallarını, harici güvenlik duvarlarını ve 80 numaralı portu Nginx'in sunduğunu kontrol edin. Tekrarlanan hatalar ana makine adı başına saatte 5 başarısız doğrulama sınırına sayılır; yeniden denemeden önce nedeni düzeltin veya önce --dry-run ile test edin.

Yönlendirme döngüsü veya uygulama http:// bağlantıları üretiyor

Uygulama özgün isteğin HTTPS kullandığını bilmiyor. X-Forwarded-Proto başlığının Adım 4'teki gibi ayarlandığından emin olun ve uygulamayı 127.0.0.1 adresindeki proxy'ye güvenecek şekilde yapılandırın. Sunucunun önünde bir CDN varsa TLS modunu, sunucuya HTTP değil HTTPS üzerinden bağlanacak şekilde ayarlayın.

Sonraki adımlar

• Daha az yapılandırma mı istiyorsunuz? Caddy ile karşılaştırın.
• Proxy ana makinelerini bir web arayüzünden Nginx Proxy Manager ile yönetin.
• Uygulama rehberlerinin konteynerleri nasıl kullandığını Docker Compose temelleri rehberinde öğrenin.
• Uygulamalarınız için bir sunucuyu Docker hosting sayfasında bulun.
• Nginx'in kendi WebSocket proxy notlarını ve Certbot kullanıcı kılavuzunu okuyun.