n8n'i VPS'te Docker Compose ile Kurma

1. Kullanım kapsamını ve sürümü doğrulayın

n8n’in topluluk sürümü fair-code yaklaşımı ve Sustainable Use License koşullarıyla dağıtılır. Kendi iç iş süreçleriniz ile n8n’i başkalarına ücretli erişim sağlayan bir hizmete dönüştürmek aynı lisans durumu değildir. Ticari bir müşteri ürünü, gömülü kullanım veya barındırılmış n8n satışı tasarlıyorsanız ilgili lisans ve kurumsal koşulları kontrol edin.

Bu rehber bir yönetilen n8n hizmeti sunulduğunu varsaymaz. VPS işletim sistemi, container, erişim ve yedek yönetimi kullanıcıya aittir. Kuruluma başlamadan önce n8n sürüm notlarını okuyun; özellikle büyük sürüm yükseltmelerinde veritabanı geçişleri ve kaldırılan ayarlar olabilir.

2. Proje klasörünü ve şifreleme anahtarını oluşturun

mkdir -p ~/n8n
cd ~/n8n
umask 077
openssl rand -hex 32 > encryption-key.txt
chmod 600 encryption-key.txt
nano .env

Üretilen değeri encryption-key.txt dosyasından .env içindeki N8N_ENCRYPTION_KEY alanına kopyalayın. Bu anahtar, n8n kimlik bilgilerini çözebilmek için gereklidir. Sonradan rastgele değiştirmeyin; veritabanı ve anahtar aynı geri yükleme setinde bulunmalıdır. Aşağıdaki anahtar metni örnektir ve gerçek kurulumda kullanılmamalıdır.

N8N_HOST=n8n.example.com
N8N_ENCRYPTION_KEY=REPLACE_WITH_GENERATED_64_HEX_CHARACTERS

chmod 600 .env
printf "%s\n" ".env" "encryption-key.txt" > .gitignore

Şifreleme anahtarını terminal kayıtlarına veya destek mesajlarına koymayın. .gitignore dosyası daha önce Git’e eklenmiş bir sırrı geçmişten silmez. Proje klasörünü paylaşmadan önce içerikleri ve geçmişi kontrol edin. Docker yetkili kullanıcılarının container ortam değişkenlerini okuyabildiğini de dikkate alın.

3. Kalıcı veriyle Compose tanımını yazın

name: serverq-n8n
services:
  n8n:
    image: n8nio/n8n:2.41.4
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      N8N_HOST: ${N8N_HOST:?Set N8N_HOST in .env}
      N8N_PORT: "5678"
      N8N_PROTOCOL: https
      N8N_EDITOR_BASE_URL: https://${N8N_HOST}
      N8N_WEBHOOK_URL: https://${N8N_HOST}/
      N8N_PROXY_HOPS: "1"
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY:?Set encryption key in .env}
      N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
      GENERIC_TIMEZONE: Europe/Istanbul
      TZ: Europe/Istanbul
    volumes:
      - n8n_data:/home/node/.n8n
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
volumes:
  n8n_data:

5678 portu yalnızca localhost’a bağlanır. N8N_PROTOCOL ve webhook adresi dışarıdaki HTTPS adresini anlatır; Nginx ile container arasındaki yerel bağlantı HTTP’dir. Tek Nginx ters vekili için N8N_PROXY_HOPS=1 kullanılır. Önüne CDN veya başka proxy eklerseniz güvenilen proxy zincirini yeniden değerlendirin.

n8n_data volume’ı SQLite veritabanı dahil kalıcı uygulama verisini saklar. PostgreSQL’e geçtiğinizde bile /home/node/.n8n dizinini kalıcı tutmak gerekir. Uygulama geçişi ayrı bir işlem olduğundan mevcut veritabanını bağlantı değişkenlerini değiştirerek otomatik taşınmış kabul etmeyin.

sudo docker compose config --quiet
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=80 n8n
curl --fail http://127.0.0.1:5678/healthz

config --quiet söz dizimini kontrol eder, sırları normal config çıktısı gibi terminale dökmez. healthz başarılı olsa bile gerçek workflow ve webhook davranışı ayrıca denenmelidir. Container sürekli yeniden başlıyorsa önce günlükleri inceleyin; sorunu veri volume’ını silerek çözmeye çalışmayın.

4. Nginx ve HTTPS bağlantısını kurun

n8n.example.com A ve varsa AAAA kaydını kendi sunucunuza yönlendirin. Nginx dosyasını /etc/nginx/sites-available/n8n olarak kaydedin. WebSocket yükseltmesi, uzun sürebilen istekler ve doğru forwarded başlıkları bu örneğe dahildir.

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

    location / {
        proxy_pass http://127.0.0.1:5678;
        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-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300s;
        proxy_buffering off;
    }
}

sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/n8n
sudo nginx -t && sudo systemctl reload nginx

Nginx ve HTTPS rehberindeki Certbot adımlarıyla bu alan adına sertifika ekleyin. İlk kullanıcı hesabını yalnızca doğru HTTPS adresinden oluşturun. Kurulum ekranını açık halde bırakmayın. Düzenleyiciye erişim ile webhook trafiğinin ihtiyaçları farklı olabilir: editöre VPN veya ek erişim kısıtı koyarken dış servislerin yetkili webhook çağrılarını engellemediğinizi doğrulayın.

5. İş akışını dış etki yaratmadan deneyin

1. İlk kullanıcıyı oluşturun ve hesap güvenlik ayarlarını tamamlayın.
2. Dış servise veri göndermeyen basit bir Manual Trigger akışı çalıştırın.
3. Deneme webhook’unu yalnızca kendi test isteğinizle doğrulayın.
4. Üretim webhook URL’sinin HTTPS ve doğru alan adı kullandığını kontrol edin.
5. Zamanlanan bir iş için Europe/Istanbul saat dilimini doğrulayın.
6. Örnek kimlik bilgisini kaydedip uygulama yeniden başladıktan sonra erişebildiğinizi kontrol edin.

Test webhook adresi ile üretim adresi farklı olabilir; üretim iş akışının etkinlik durumunu kontrol edin. Bir işin yeniden denenmesi aynı kaydı iki kere oluşturmamalıdır. Ödeme, bildirim veya kayıt yazan akışlarda kimlik doğrulama, tekrar güvenliği ve hata dalını gerçek sisteme açılmadan önce tasarlayın.

Örnek kurulum gelişmiş Code node izolasyonu veya yoğun queue mode mimarisini kapsamaz. Üretimde kullanıcı kodu çalıştırıyorsanız n8n’in haricî task runner güvenlik önerilerini inceleyin. Güvenilmeyen kişilere workflow düzenleme yetkisi vermek sunucudaki sırlar ve erişilen servisler üzerinde risk oluşturabilir.

6. Veriyi ve anahtarı birlikte koruyun

SQLite kullanırken tutarlı dosya yedeği için planlı kısa bir durdurma veya SQLite’ın desteklediği tutarlı yedekleme yöntemi kullanın. Container çalışırken yalnızca database.sqlite dosyasını kopyalamak ilişkili günlük dosyalarını kaçırabilir. Export edilen workflow dosyaları tam instance yedeğinin yerine geçmez.

Güncellemeden önce n8n sürüm notlarını inceleyin ve yedeği izole ortamda açın. compose.yaml içindeki sürümü bilinçli değiştirip pull ve up -d uygulayın. Eski image’a dönmek veritabanı geçişini geri almaz; gerektiğinde uyumlu veri yedeğiyle dönülür. Yük büyüdüğünde execution saklama süresi, eş zamanlılık, büyük dosyalar ve veritabanı kullanımını ölçerek kapasite planlayın.