Nginx Proxy Manager Docker ile nasıl kurulur ve yönetim paneli nasıl korunur

Nginx Proxy Manager (NPM), Nginx ve Let's Encrypt'in üzerine bir web arayüzü koyar. Server blokları yazmak yerine proxy host'ları tıklayarak oluşturursunuz: bir alan adı, yönlendirdiği uygulama ve NPM'in sizin için istediği ve yenilediği bir sertifika. Grafik arayüz tercih eden yöneticilere ve birçok uygulama için tek sunucuyu paylaşan ekiplere uygundur. Bu rehber NPM'i resmi imajından Docker Compose ile kurar, yönetim portunu internetten uzak tutar, yönetici hesabını bir SSH tüneli üzerinden oluşturur, uygulamaları paylaşılan bir Docker ağı üzerinden bağlar, HTTPS ve erişim listeleri ekler, yönetim panelinin kendisini güvenle yayınlar; yedekleme, güncelleme ve sorun gidermeyi ele alır.

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

NPM uygulamalarınıza iki tarafın da katıldığı bir Docker ağı üzerinden ulaşır. Bu ağı bir kez oluşturun:

docker network create proxy

Adım 2 — Compose projesini oluşturun

Proje klasörünü oluşturun:

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

/opt/npm/compose.yaml dosyasını oluşturun. Dosya resmi örneği izler, iki değişiklikle: 81 numaralı yönetim portu yalnızca 127.0.0.1 üzerinde yayınlanır ve konteyner proxy ağına katılır.

services:
  app:
    image: jc21/nginx-proxy-manager:2.16.0
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "127.0.0.1:81:81"
    environment:
      TZ: "Etc/UTC"
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    networks:
      - proxy

networks:
  proxy:
    name: proxy
    external: true

Bölümlerin görevleri:

• İmaj etiketi — resmi kurulum sayfası bir sürümü sabitler; 2.16.0 bu rehber yazılırken güncel sürümdür. En yeni etiket için projenin GitHub sürümler sayfasına bakın ve onu kullanın.
• Portlar — 80 ve 443 sitelerinizi sunar ve herkese açık olmalıdır. 81 numaralı port yönetim arayüzüdür; 127.0.0.1 üzerinde onu yalnızca sunucunun kendisi açabilir.
• ./data — SQLite veritabanı (database.sqlite), üretilen Nginx yapılandırmaları, özel sertifikalar ve loglar.
• ./letsencrypt — Let's Encrypt sertifikaları ve hesap anahtarları.
• TZ — logların yerel saati göstermesi için saat diliminizi ayarlayın; örneğin Europe/Istanbul.

NPM varsayılan olarak SQLite kullanır. Kurulum sayfasında belgelenen DB_MYSQL_* veya DB_POSTGRES_* ortam değişkenleriyle MySQL/MariaDB ya da PostgreSQL de kullanabilir; tek bir sunucu için SQLite yeterlidir. Sunucuda IPv6 yoksa environment altına DISABLE_IPV6: "true" ekleyin.

Adım 3 — NPM'i başlatın ve yönetici hesabını oluşturun

Konteyneri başlatın ve ilk açılışını tamamlamasını bekleyin:

docker compose up -d
docker compose logs -f app

İlk çalıştırmada NPM anahtarlarını üretir ve veritabanı tablolarını oluşturur; bu bir iki dakika sürebilir. Loglar durulduğunda izlemeyi Ctrl+C ile bırakın ve durumu kontrol edin:

docker compose ps

81 numaralı port yalnızca 127.0.0.1 üzerinde dinlediği için onu kendi bilgisayarınızdan bir SSH tüneliyle açın:

ssh -L 8181:127.0.0.1:81 your-user@203.0.113.10

Bu oturumu açık tutun ve tarayıcıda http://localhost:8181 adresine gidin. 2.13.0 sürümünden beri varsayılan bir giriş yoktur: NPM, ilk yöneticiyi oluşturduğunuz bir kurulum ekranı gösterir. Gerçek e-posta adresinizi ve tercihen bir parola yöneticisinden alınmış uzun, benzersiz bir parola kullanın.

Giriş yaptıktan sonra kullanıcı ayarlarınızdan yönetici hesabı için iki adımlı doğrulamayı açın; NPM 2.13.6 sürümünden beri TOTP uygulamalarını destekler.

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

81 numaralı port için ufw'ye güvenmeyin. Docker belgelerine göre yayınlanan konteyner portları ufw'yi atlar; çünkü Docker trafiği ufw kuralları uygulanmadan önce yönlendirir. Portu gizli tutan şey, compose.yaml içinde 127.0.0.1'e bağlanmasıdır. Kapalı olduğunu başka bir makineden kontrol edin:

nc -vz 203.0.113.10 81

Bağlantı reddedilmeli veya zaman aşımına uğramalıdır.

Adım 5 — Bir uygulamayı proxy ağına bağlayın

NPM istekleri proxy ağı üzerinden uygulamalara adlarıyla iletir. Uygulamanın compose.yaml dosyasında ports: kaydını kaldırın ve ağı ekleyin; uygulamanın kendi veritabanına ulaşmaya devam etmesi için default ağını da koruyun:

services:
  app:
    # imaj, ortam değişkenleri ve volume'lar uygulamanın rehberindeki gibi kalır
    networks:
      - default
      - proxy

networks:
  proxy:
    name: proxy
    external: true

Uygulamanın klasöründe docker compose up -d çalıştırın, ardından konteynerin adını bulun:

docker network inspect proxy | grep '"Name"'

NPM'de yönlendirme ana makine adı olarak konteyner adını (örneğin n8n-n8n-1) kullanın. Servis adları da çözümlenir, ancak birçok proje servisine app veya server adını verir ve paylaşılan bir ağda aynı adlı iki servis çakışır. Konteyner adı ise sunucuda benzersizdir.

Adım 6 — HTTPS'li bir proxy host ekleyin

Yönetim arayüzünde Hosts, ardından Proxy Hosts bölümünü açın ve yeni bir proxy host ekleyin:

1. Domain names: app.example.com. DNS kaydı sunucuyu zaten göstermelidir.
2. Scheme: http. Uygulama Docker ağının içinde düz HTTP konuşur; HTTPS'i NPM üstlenir.
3. Forward hostname / IP: Adım 5'teki konteyner adı. Forward port: uygulamanın konteyner içinde dinlediği port; örneğin 5678.
4. Uygulama canlı güncellemeler kullanıyorsa WebSocket support seçeneğini ve Block common exploits seçeneğini açın.
5. SSL sekmesinde yeni bir Let's Encrypt sertifikası isteyin ve HTTP'yi HTTPS'e yönlendiren Force SSL seçeneğini açın. HTTP/2 desteği de açık olabilir.

Etiketler sürümler arasında biraz farklı olabilir. 2.13.0 sürümünden beri NPM sertifika isterken e-posta adresi veya koşulların kabulünü sormaz. Host'u kaydedin ve test edin:

curl -I http://app.example.com
curl -I https://app.example.com

HTTP isteği HTTPS'e bir yönlendirme döndürür, HTTPS isteği ise uygulamanızın yanıtını döndürür. NPM sertifikaları kendisi yeniler.

Adım 7 — Erişim listeleriyle erişimi kısıtlayın

Bir erişim listesi (access list), bir proxy host'a kimlerin ulaşabileceğini sınırlar. Access Lists bölümünü açın ve bir liste oluşturun:

• yetkilendirme sekmesinde HTTP basic authentication için kullanıcı adları ve parolalar ekleyin,
• erişim sekmesinde belirli IP adreslerine veya aralıklarına (örneğin ofis IP'nize) izin verin ve geri kalan her şeyi reddedin,
• ziyaretçinin kurallardan herhangi birini mi yoksa hepsini mi sağlaması gerektiğini seçin.

Ardından proxy host'u açın, erişim listesini seçin ve kaydedin. Erişim listelerini kendi girişi olmayan araçlar için kullanın. Kendisi HTTP basic authentication kullanan uygulamalarda yalnızca IP kurallarını kullanın: projenin SSS sayfası, erişim listesinin ve uygulamanın aynı Authorization başlığını kullanacağını ve iki girişten birinin bozulacağını açıklar.

Adım 8 — Yönetim panelini güvenle yayınlayın (isteğe bağlı)

NPM'i yönetmenin en güvenli yolu SSH tünelidir. Yönetim panelini bunun yerine normal bir HTTPS adresinde istiyorsanız NPM'in kendisine proxy yapmasını sağlayın:

1. Yalnızca kendi IP adreslerinize izin veren ve diğer her şeyi reddeden bir erişim listesi oluşturun.
2. npm.example.com için scheme http, forward hostname 127.0.0.1 ve forward port 81 olan bir proxy host ekleyin. Konteynerin içinde 127.0.0.1 NPM'in kendisidir; burada hedef tam olarak budur.
3. Bir sertifika isteyin, Force SSL seçeneğini açın ve erişim listesini seçin.

Kendinizi dışarıda bırakırsanız tünelin çalışmaya devam etmesi için 81 numaralı portu compose.yaml içinde 127.0.0.1'e bağlı tutun. İki adımlı doğrulama ve IP erişim listesiyle yönetim paneli üç katmanla korunur.

Yedekleme ve geri yükleme

NPM'in bildiği her şey /opt/npm içindedir: compose.yaml, data/ (veritabanı, yapılandırmalar, loglar) ve letsencrypt/ (sertifikalar ve anahtarlar). SQLite veritabanının tutarlı bir durumda kopyalanması için konteyneri kısa bir süre durdurun. Klasörler root'a ait olduğu için sudo kullanın:

sudo mkdir -p /opt/backups
cd /opt/npm
docker compose stop
sudo tar czf /opt/backups/npm-$(date +%F).tar.gz -C /opt npm
docker compose start

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

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

Uygulama projelerinizi Adım 5'teki gibi yeniden proxy ağına bağlayın. Özel anahtarlar içerdiği için arşivi gizli tutun ve sunucunun dışına kopyalayın. MySQL/MariaDB veya PostgreSQL'e geçtiyseniz o veritabanının dökümünü de kendi aracıyla alın.

Nginx Proxy Manager güncelleme

En yeni sürüm için GitHub sürümler sayfasına bakın ve notlarını okuyun; bazı sürümler ek yükseltme adımları listeler. Yedek alın, compose.yaml içindeki imaj etiketini örneğin 2.16.0 değerinden yeni sürüme değiştirin, ardından imajı çekip konteyneri yeniden oluşturun:

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

NPM açılışta veritabanını ve diğer gereksinimleri kendiliğinden günceller. Ardından yönetim arayüzünü açın ve proxy host'larınızın ve sertifikalarınızın listelendiğini kontrol edin.

Sorun giderme

502 Bad Gateway

NPM uygulamaya ulaşamıyor. Yönlendirme ana makine adının uygulamanın konteyner adı olduğunu (127.0.0.1 değil), uygulamanın proxy ağına bağlı olduğunu (docker network inspect proxy) ve yönlendirme portunun ana makine portu değil konteyner içindeki port olduğunu kontrol edin. Ardından uygulamanın klasöründe docker compose logs app çıktısına bakın.

Sertifika isteği Internal Error ile başarısız oluyor

Let's Encrypt alan adını doğrulayamadı. A ve AAAA kayıtlarının bu sunucuyu gösterdiğini (dig +short A app.example.com), 80 numaralı portun internetten erişilebilir olduğunu ve hiçbir AAAA kaydının sunucunun yanıt vermediği bir adresi göstermediğini kontrol edin. Ayrıntılı hata için /opt/npm içinde docker compose logs app çıktısını okuyun. 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.

Yönetim arayüzünü açamıyorum

SSH tünelinin çalıştığından ve tarayıcıda sunucunun adresine değil, kendi bilgisayarınızda http://localhost:8181 adresine gittiğinizden emin olun. Konteynerin çalıştığını docker compose ps ile kontrol edin ve ilk başlatmadan sonra ona bir dakika verin.

Erişim listesi ekledikten sonra uygulamaya giriş çalışmıyor

Erişim listesi ve uygulama aynı Authorization başlığını kullanıyor. Erişim listesinden kullanıcı adı ve parola kurallarını kaldırıp yalnızca IP kurallarını bırakın veya uygulamanın kendi girişine güvenin.

Address family not supported by protocol

Sunucuda IPv6 yok, ancak NPM onun üzerinde dinlemeye çalışıyor. compose.yaml içinde environment altına DISABLE_IPV6: "true" ekleyin ve docker compose up -d çalıştırın.

Bind for 0.0.0.0:80 failed: port is already allocated

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, durdurup devre dışı bırakın, ardından docker compose up -d komutunu yeniden çalıştırın.

Sonraki adımlar

• Burada kullanılan Compose özelliklerini Docker Compose temelleri rehberinde öğrenin.
• Kod olarak yapılandırma mı tercih edersiniz? Caddy veya Traefik ile karşılaştırın.
• Yönetim tünelinizi de koruyan SSH erişimini SSH anahtarlarını ayarlayın rehberiyle güçlendirin.
• Uygulamalarınız için bir sunucuyu Docker hosting sayfasında bulun.
• Özel Nginx parçacıkları ve ortam seçenekleri için resmi gelişmiş yapılandırma notlarını okuyun.