n8n VDS Kurulumu: Docker ile Güvenli Kurulum Rehberi

n8n VDS kurulumu: n8n'i VDS üzerinde Docker Compose ile kurup domain, HTTPS, kalıcı veri ve ilk test akışını aynı plan içinde tamamlamak isteyenler için pratik rehber

n8n VDS kurulumu, n8n’i kendi sanal sunucunuzda Docker Compose ile çalıştırıp domain, HTTPS, kalıcı veri ve ilk test akışını güvenli biçimde hazır hale getirme sürecidir. Ubuntu tabanlı bir VDS üzerinde PostgreSQL, reverse proxy ve sabit bir encryption key ile kurulum yaptığınızda, paneli dışarıdan erişilebilir kılarken veriyi de sunucuda kalıcı tutarsınız. Doğru kurulumda n8n yalnızca açılmaz; yeniden başlatmadan sonra aynı credential’larla çalışır, webhook adresleri doğru üretir ve ilk workflow testleri sorunsuz geçer. Bu rehber, teknik veya yarı teknik kullanıcıların kurulum öncesi hazırlıkları tamamlamasına, ilk yapılandırma değişkenlerini doğru seçmesine, test çalıştırması yapmasına ve gerektiğinde güvenli biçimde geri almasına odaklanır. Dağıtımınıza göre paket ve servis adları değişebileceği için örnekleri Ubuntu/Debian benzeri bir ortam varsayımıyla okuyun; üretimde asıl hedef, kalıcı volume, doğru public base URL ve kontrollü geri dönüş planıdır.

n8n VDS kurulumu için doğru mimari

n8n, VDS üzerinde kurulduğunda en çok kontrol ve kalıcılık kazandırır. Bu yöntem, harici API’lere bağlanan akışlar, webhook ile gelen istekler, Cron tabanlı otomasyonlar ve ekip içi kullanım için uygundur. Buna karşılık, yalnızca kısa süreli deneme yapacaksanız ya da sunucuyu yönetmek istemiyorsanız daha hafif bir kurulum yolu seçmek daha mantıklı olabilir.

Uygun olduğu durumlar: 7/24 çalışan akışlar, webhook’lar, API entegrasyonları, veri kaybı riski taşımayan üretim kullanımı.
Daha az uygun olduğu durumlar: Tek seferlik testler, düşük kaynaklı geçici denemeler, sunucu yönetimi yapmak istemeyen kullanıcılar.

Bu kurulumda üç parçayı birlikte düşünün: uygulama konteyneri, kalıcı veritabanı ve dış dünyaya açılan reverse proxy. Üçü birlikte doğru çalışırsa n8n sadece açılmaz; aynı zamanda yeniden başlatmalardan sonra da aynı kimlik ve aynı workflow’larla devam eder.

Kurulum öncesi hazırlık ve uyumluluk

Ubuntu veya Debian tabanlı bir VDS varsayımıyla ilerliyorum. Farklı bir dağıtım kullanıyorsanız paket adları ve servis adları değişebilir; önce kendi sisteminizde karşılıklarını doğrulayın. En azından aşağıdakilere sahip olun:

SSH erişimi ve sudo yetkisi
İnternete bakan bir alan adı veya alt alan adı
VDS IP’sine yönlenen bir A kaydı
80 ve 443 numaralı portlarda çakışma olmaması
Kurulumdan önce alınmış bir dosya veya volume yedeği

Kaynak tarafında ise işinizi kolaylaştırmak için şu varsayımla düşünün: küçük testlerde sınırlı kaynaklar yeterli olabilir, fakat üretimde veritabanı ve tarayıcı oturumu sürekli açık kalacağı için biraz nefes payı bırakmak daha güvenlidir. Özellikle yalnızca port 5678 ile internete açmak yerine domain ve HTTPS katmanını baştan kurmak sonraki düzeltme işini azaltır.

Docker Compose ile kurulumu başlatın

Bu örnekte Docker ve Docker Compose eklentisini kullanıyorum. Paket adları dağıtıma göre değişebilir; eğer sizde docker.io yerine başka bir paket adı varsa kendi depo yapınıza uyarlayın. Önce temel araçları doğrulayın, sonra çalışma dizinini hazırlayın.

sudo apt update
sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker
docker version
docker compose version
sudo mkdir -p /opt/n8n
cd /opt/n8n

Komutlar sonunda Docker istemci ve sunucu bilgisini görüyorsanız sonraki adıma geçebilirsiniz. docker compose version çıktısı da plugin’in yüklü olduğunu doğrulamalıdır.

Şimdi docker-compose.yml dosyasını oluşturun. Aşağıdaki örnek, n8n için kalıcı veri, PostgreSQL için ayrı bir veritabanı ve HTTPS için Caddy reverse proxy kullanır. Alan adını ve parolayı ilk çalıştırmadan önce değiştirin.

services:
  postgres:
    image: postgres:alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: BUNU_GUCLU_BIR_PAROLAYLA_DEGISTIRIN
      POSTGRES_DB: n8n
    volumes:
      - postgres_data:/var/lib/postgresql/data

  n8n:
    image: n8nio/n8n
    restart: unless-stopped
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: BUNU_GUCLU_BIR_PAROLAYLA_DEGISTIRIN
      N8N_HOST: otomasyon.ornekalanadi.com
      N8N_PROTOCOL: https
      N8N_EDITOR_BASE_URL: 
      WEBHOOK_URL: 
      N8N_ENCRYPTION_KEY: BUNU_UZUN_VE_TAHMIN_EDILEMEZ_BIR_DEGERLE_DEGISTIRIN
      GENERIC_TIMEZONE: Europe/Istanbul
    depends_on:
      - postgres
    volumes:
      - n8n_data:/home/node/.n8n

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - n8n

volumes:
  postgres_data:
  n8n_data:
  caddy_data:
  caddy_config:

Yanına bir de Caddyfile koyun:

otomasyon.ornekalanadi.com {
  encode gzip
  reverse_proxy n8n:5678
}

Bu yapı size şunu sağlar: n8n içeride 5678 portunda çalışır, dışarıya ise HTTPS üzerinden açılır. Alan adı henüz VDS IP’sine çözülmüyorsa Caddy sertifika alamaz; bu yüzden önce DNS kaydını doğrulamak gerekir. Eğer sunucuda zaten bir web sunucusu veya kontrol paneli 80 ve 443 portlarını kullanıyorsa, aynı anda ikinci bir reverse proxy çalıştırmayın; tek bir yayın katmanı seçin.

docker compose up -d
docker compose ps
docker compose logs -f --tail=50

Beklenen durum, üç servisin de Up görünmesi ve loglarda n8n ile veritabanı bağlantısının hata vermeden başlamasıdır. İlk açılışta Caddy sertifikayı alırsa alan adı üzerinden panel ekranı açılır.

İlk yapılandırma: hangi ayar neyi değiştirir?

Kurulumun en önemli kısmı çoğu zaman kod değil, değişken yönetimidir. Aşağıdaki alanlar küçük görünür ama yanlış ayarlanırsa webhook, giriş ve veri saklama tarafında sorun üretir.

Ayar	Ne değiştirir?	Güvenli başlangıç	Risk / not
`N8N_ENCRYPTION_KEY`	Kredansiyel ve gizli alanların şifrelenmesini sabitler.	Uzun, tahmin edilemez ve yalnız size ait bir değer.	Sonradan değiştirmek kayıtlı kredansiyelleri okunamaz hale getirebilir.
`DB_TYPE=postgresdb`	Veriyi SQLite yerine PostgreSQL’de tutar.	Üretim için PostgreSQL.	Küçük testlerde SQLite yeterli olabilir; üretimde daha kırılgan kalabilir.
`WEBHOOK_URL`	Dış dünyaya dönen webhook adresini belirler.	HTTPS kullanan public alan adı.	Yanlış adres, tetikleyicilerin beklenen URL ile çalışmamasına yol açar.
`N8N_EDITOR_BASE_URL`	Editörün yönlendirme ve link üretim adresini ayarlar.	Public alan adı ile aynı kök URL.	Yanlış değer giriş yönlendirmesinde tutarsızlık oluşturabilir.
`GENERIC_TIMEZONE`	Cron zamanlamalarının ve arayüz varsayımlarının saat dilimini belirler.	`Europe/Istanbul`	Yanlış saat dilimi, zamanlanmış işlerin yanlış saatlerde çalışmasına neden olur.

Bu noktada iki güvenli kuralı akılda tutun: birincisi, üretimde N8N_ENCRYPTION_KEY sonradan değişmemeli; ikincisi, public adres değişirse WEBHOOK_URL ve N8N_EDITOR_BASE_URL birlikte güncellenmeli. Böylece hem login davranışı hem de dış entegrasyonlar tutarlı kalır.

İlk açılış ve test workflow’u

Tarayıcıdan alan adını açtığınızda n8n arayüzünü görmelisiniz. İlk girişte owner hesabı oluşturursunuz; bu aşamada güçlü bir parola ve erişimi kontrollü bir e-posta kullanın. Ardından boş bir workflow açıp basit bir test yapın:

Bir Manual Trigger veya Cron Trigger ekleyin.
Arkasına basit bir Set ya da HTTP Request node’u koyun.
Workflow’u kaydedin ve Execute Workflow ile çalıştırın.
Executions ekranında yeşil tamamlanma durumu arayın.

Webhook ile çalışacaksanız ek bir kontrol gerekir: dış servislerin vuracağı URL’nin gerçekten public domain üzerinden dönmesi gerekir. İlk testte bir istek alıyorsanız ama dış servis çalışmıyorsa sorun çoğu zaman neredeyse her zaman WEBHOOK_URL ya da proxy katmanındadır, node tarafında değil.

Başarılı kurulumda şu davranışları görmelisiniz: panel HTTPS üzerinden açılır, workflow kaydedilir, execution listesi görünür, container yeniden başlatıldığında veriler kaybolmaz. Bu dört kontrol, kurulumun sadece açıldığını değil, kalıcı olduğunu da gösterir.

Günlük kullanımda neyi izlemelisiniz?

n8n kurulduktan sonra asıl iş akışıdır. Her yeni entegrasyon için credential oluştururken şifreleri workflow içine gömmeyin; n8n credential mekanizmasını kullanın. Böylece erişim bilgilerini tek yerde toplar, ileride yetki revizyonu yaptığınızda daha temiz ilerlersiniz.

Kısa test akışı: Yeni bir node eklemeden önce küçük veriyle deneme yapın.
Execution log: Hata olduğunda ilk bakacağınız yer burası olsun; HTTP durum kodu, response body ve node adı genellikle ipucu verir.
Yedek rutini: Veritabanı ve volume yedeğini düzenli planlayın; sorun çıktığında en hızlı geri dönüş bu yoldur.
Güncelleme disiplini: Yeni sürümü önce düşük riskli bir ortamda deneyin, sonra canlıya taşıyın.

Özellikle webhook kullanan akışlarda istek gerçekten n8n’e ulaşıyor mu, yoksa reverse proxy mi kesiyor sorusunu ayırmak önemlidir. Tarayıcıda editörün açılması tek başına yeterli sayılmaz; Executions kayıtlarında girişin oluşması, akışın içinde veri gördüğünüzü ve tetikleyicinin çalıştığını gösterir. Eğer HTTP Request node’u ile dış servise çıkış yapıyorsanız, 400 ve 401 hataları çoğu zaman payload veya kimlik doğrulama sorununu; 403 ise yetki ya da IP kısıtını; 5xx ise çoğu zaman dış servis tarafındaki geçici problemi işaret eder.

İşin en sağlıklı yanı, her büyük değişiklikten sonra küçük bir doğrulama alışkanlığı kurmaktır. Bir nodeları değiştirdiğinizde, ilgili workflow’u elle bir kez çalıştırın; bir environment değişkenini güncellediğinizde önce paneli yenileyin, sonra sample request deneyin; bir proxy kuralı eklediğinizde hem HTTPS hem de yönlendirme başlıklarını kontrol edin. Böylece sorunları büyümeden yakalarsınız.

Sık görülen sorunlar ve pratik çözümler

Kurulumlarda en çok aynı birkaç hata tekrar eder. Bunların çoğu n8n’den değil, çevre bileşenlerinden kaynaklanır.

Alan adı açılmıyor: DNS A kaydını ve 80/443 portlarını kontrol edin. Caddy loglarında sertifika alma hatası varsa önce DNS’i düzeltin.
Giriş döngüsü oluşuyor: N8N_EDITOR_BASE_URL ile N8N_HOST değerleri birbiriyle uyumlu olmayabilir. Public URL’yi tek biçimde kullanın.
Webhook yanlış adrese gidiyor: WEBHOOK_URL değerini public HTTPS alan adıyla eşleştirin. Lokal IP veya port kullanmayın.
Yeniden başlatınca credential kayboluyor gibi: N8N_ENCRYPTION_KEY değişmiş olabilir ya da volume kalıcı değildir.
Workflow saati kayık: GENERIC_TIMEZONE yanlışsa Cron tetikleyicileri beklenmeyen saatte çalışır.

Buradaki farkı ayırmanın iyi yolu şudur: tarayıcıda panel görünüyor ama entegrasyon çalışmıyorsa sorun büyük ihtimalle URL, header veya credential tarafındadır. Panel bile açılmıyorsa sorun daha çok proxy, DNS, port ya da servis ayağa kalkma aşamasındadır. Bu ayrım zaman kazandırır ve gereksiz yeniden kurulum ihtiyacını azaltır.

Bir diğer pratik nokta, ilk denemede her şeyi tek seferde geniş kapsamlı kurmaya çalışmamaktır. Önce panel ve giriş, sonra kalıcılık, ardından webhook ve en son harici API bağlantısı. Her katmanı ayrı test etmek, hata kaynağını daraltır.

Mevcut Nginx veya panel kullananlar için alternatif yol

Eğer sunucuda zaten Nginx, Apache ya da bir hosting panelinin kendi web sunucusu varsa, Caddy eklemek şart değildir. Böyle bir senaryoda n8n’i içeride yine 5678 portunda çalıştırıp dışa açılmayı mevcut ters proxy üzerinden yapabilirsiniz. Burada kritik nokta, tek bir yayın katmanının otorite olmasıdır; aynı alan adı için iki farklı reverse proxy tanımlamayın.

Mevcut web sunucusu kullanıldığında SSL yönetimi, yönlendirme ve başlık iletimi panelin kendi yapılandırmasına göre değişir. Bu nedenle Host, X-Forwarded-Proto ve benzeri proxy başlıklarının doğru geçtiğini doğrulamak gerekir. Başlıklar eksikse n8n kendini HTTP üzerinde sanabilir ve URL üretimi bozulabilir.

Bu alternatif yol, sunucuda zaten standart bir yayın altyapısı varsa mantıklıdır; ama ilk kez kurulum yapan biri için Docker içindeki Caddy yaklaşımı daha okunur kalır. Daha az parça, daha az belirsizlik demektir.

Geri alma ve güvenli kapatma

Kurulum canlı bir değişiklik sayılır; bu yüzden geri alma planı baştan olmalı. Hata yaşarsanız amaç sistemi bozmak değil, güvenli biçimde önceki duruma döndürmektir.

Önce workflow ve credential yedeğinizin varlığını doğrulayın.
Gerekirse docker compose logs ile hata anını inceleyin.
Yayın sorununda proxy katmanını geçici olarak durdurun; veritabanını hemen silmeyin.
Servisi kapatmanız gerekiyorsa docker compose down kullanın.
Canlı ortamda docker compose down -v komutunu rastgele çalıştırmayın; bu, volume verisini silebilir.

Eğer kurulumdan tamamen geri dönmek istiyorsanız önce kullanılacak yedeğin güncel olduğundan emin olun, sonra compose dosyasını ve ilgili volume’leri bilinçli şekilde kaldırın. Burada güvenli olan yaklaşım, önce dış erişimi kapatmak, sonra veri katmanını ele almaktır. Böylece servis kullanıcıya açık kalırken iç veri kaybı riski azaltılır.

Geri alma sırasında şunu unutmayın: N8N_ENCRYPTION_KEY sabit tutulmuşsa veriye dönüş daha kolay olur. Bu anahtar değişmişse, eski credential kayıtları okunamayabilir. Bu nedenle encryption key dosya veya parola yönetiminde ayrı ve kontrollü tutulmalıdır.

Son kontrol listesi

Alan adı doğru A kaydına gidiyor mu?
docker compose ps çıktısında servisler Up mı?
Panel HTTPS ile açılıyor mu?
WEBHOOK_URL public alan adını gösteriyor mu?
N8N_ENCRYPTION_KEY sabit ve güvenli mi?
Bir test workflow’u Executions ekranında görünüyor mu?
Sunucu yeniden başlatıldığında veri korunuyor mu?

Bu yedi madde tamamlanıyorsa kurulum sadece çalışmıyor, aynı zamanda sürdürülebilir biçimde kurulmuş sayılır. Bundan sonraki aşamada ek entegrasyonlar ekleyebilir, webhook’ları çoğaltabilir ve erişim politikalarını daraltabilirsiniz. Buradaki temel başarı ölçütü şudur: n8n paneli açılıyor, doğru URL’leri üretiyor, kayıtlı akışlar kaybolmuyor ve siz de sistemi gerektiğinde güvenle kapatıp açabiliyorsunuz.

Sık Sorulan Sorular

n8n’i VDS üzerinde kurmak için en güvenli başlangıç yöntemi nedir?

En güvenli başlangıç yöntemi, Docker Compose ile n8n, PostgreSQL ve reverse proxy katmanını ayrı tutmaktır. Bu yapı kalıcı veri, kolay güncelleme ve kontrollü geri alma sağlar. İlk kurulumda yalnızca panelin açılmasına değil, test workflow'unun çalışmasına ve yeniden başlatma sonrası verinin korunmasına bakmak gerekir.

n8n VDS kurulumu sırasında WEBHOOK_URL neden önemlidir?

WEBHOOK_URL, dış servislerin n8n'e hangi public adresten ulaşacağını belirler. Değer yanlışsa webhook tetikleri lokal adrese dönebilir veya hiç çalışmayabilir. Public domain, HTTPS ve reverse proxy ayarlarıyla aynı kökte olmalıdır; aksi halde entegrasyonlar panel açık olsa bile hata verir.

N8N_ENCRYPTION_KEY sonradan değiştirilirse ne olur?

N8N_ENCRYPTION_KEY sonradan değiştirilirse kayıtlı credential verileri okunamaz hale gelebilir. Bu anahtar kurulumdan sonra sabit kalmalıdır ve güvenli bir yerde saklanmalıdır. Değişiklik gerekiyorsa önce yedek planı yapılmalı, ardından yeni kurulum veya kontrollü taşıma düşünülmelidir.

Panel açılıyor ama workflow çalışmıyorsa önce nereyi kontrol etmeliyim?

Önce Executions ekranını, ardından ilgili node'un log ve response ayrıntılarını kontrol etmelisiniz. 400 ve 401 genellikle payload ya da kimlik doğrulama sorununu, 403 yetki kısıtını, 5xx ise çoğu zaman dış servis tarafını işaret eder. Eğer webhook varsa WEBHOOK_URL ve proxy başlıkları ayrıca gözden geçirilmelidir.

n8n kurulumunu geri almak istersem veri silmeden ne yapmalıyım?

Önce docker compose down ile servisi güvenli biçimde durdurmalı, sonra volume ve compose dosyalarına dokunmadan logları incelemelisiniz. Canlı ortamda docker compose down -v kullanmak veriyi silebilir, bu yüzden yedeğiniz doğrulanmadan uygulanmamalıdır. Geri alma kararı, önce erişimi kapatıp sonra veri katmanını ele alacak şekilde verilmelidir.