n8n kurulumu: Docker ve npm ile localhost’a adım adım

n8n bir iş akışı (workflow) otomasyon aracıdır: servisleri ve uygulamaları birbirine bağlar, tekrarlayan işler kendiliğinden yapılır; örneğin sitenizdeki her yeni form bir tabloya eklenir ve bir uzmana mesaj gider ya da her sabah bir rapor hazır olur. n8n kurumun kendi sunucusuna kurulabilir; bu da verilerinin dış servislere gitmesini istemeyen ekipler için onu cazip kılar.

Bu makale, iş akışlarını sunucuya taşımadan önce öğrenmek, kurmak ve test etmek için n8n’i kendi bilgisayarınıza (localhost) nasıl kuracağınızı anlatıyor. Komutlar, yazıldığı tarihteki resmî n8n dokümantasyonuna dayanıyor.

Hangi kurulum yöntemi?

Üç temel seçenek var:

• Docker: n8n’in kendisinin önerdiği yöntem. n8n sistemin geri kalanından ayrı çalışır, kurulumu ve kaldırılması kolaydır ve bilgisayarınızdaki Node.js sürümüne bağlı değildir.
• Docker Compose: yine Docker, ama ayarlar bir dosyada durur ve bilgisayar yeniden başladıktan sonra n8n kendiliğinden açılır. Günlük kullanım için en iyi seçim.
• npm: Node.js zaten yüklüyse ve sadece hızlıca denemek istiyorsanız. n8n dokümantasyonuna göre npm kurulumu 3. sürümden itibaren bırakılıyor; uzun süreli kullanım için Docker’ı seçin.

Ön koşullar

• Windows ve macOS: Docker Desktop’ı kurun; Docker Compose da onunla gelir. Windows’ta Docker Desktop WSL 2 kullanır.
• Masaüstü olmayan Linux: Docker Engine ve Docker Compose eklentisini ayrı ayrı kurun.
• npm için: Node.js 20.19 ile 24 arası.

Docker’ı kurduktan sonra çalıştığından emin olmak için terminalde şu komutları çalıştırın:

docker --version
docker compose version

1. yöntem: n8n’i Docker ile çalıştırmak

Önce, konteyner silindiğinde veriler ve iş akışları kaybolmasın diye bir volume oluşturun:

docker volume create n8n_data

Sonra n8n’i çalıştırın (Windows’ta \ olmadan tek satırda yazın):

docker run -it --rm \
  --name n8n \
  -p 127.0.0.1:5678:5678 \
  -e GENERIC_TIMEZONE="Europe/Istanbul" \
  -e TZ="Europe/Istanbul" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

Her bölümün anlamı:

• -p 127.0.0.1:5678:5678: 5678 portu yalnızca bu bilgisayarda açılır, ağdaki diğerleri erişemez. n8n dokümantasyonu -p 5678:5678 kullanır, bu da portu tüm ağ arayüzlerinde açar; localhost için sınırlamak daha güvenlidir.
• GENERIC_TIMEZONE: Schedule Trigger gibi zamanlanmış düğümlerin saat dilimi. Ayarlanmazsa sabah 8’de çalışması gereken iş akışı başka bir saatte çalışır.
• TZ: konteyner içindeki sistemin saat dilimi.
• -v n8n_data:/home/node/.n8n: n8n’in tüm verileri (veritabanı, iş akışları, kimlik bilgileri ve şifreleme anahtarı) volume’da saklanır.
• --rm: konteyner durduğunda silinir; veriler volume’da kalır.

Şimdi tarayıcıda http://localhost:5678 adresini açın. n8n’i durdurmak için aynı terminalde Ctrl+C tuşlarına basın.

2. yöntem: günlük kullanım için Docker Compose

Örneğin n8n adında bir klasör oluşturun ve içine şu içerikle compose.yaml adlı bir dosya koyun:

services:
  n8n:
    image: n8nio/n8n
    container_name: n8n
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      - GENERIC_TIMEZONE=Europe/Istanbul
      - TZ=Europe/Istanbul
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Aynı klasörde:

docker compose up -d

n8n arka planda çalışır ve restart: unless-stopped sayesinde bilgisayar yeniden başladığında tekrar açılır. Birkaç kullanışlı komut:

docker compose ps
docker compose logs -f n8n
docker compose down

İlki durumu, ikincisi günlükleri gösterir, üçüncüsü n8n’i durdurur; veriler volume’da kalır.

3. yöntem: npm ile kurulum

Uygun bir Node.js sürümünüz varsa kurmadan denemek için:

npx n8n

Ya da kalıcı olarak kurup çalıştırın:

npm install n8n -g
n8n start

Bu yöntemde veriler kullanıcı klasörünüzdeki .n8n klasöründe saklanır.

İlk giriş

http://localhost:5678 adresini açtığınızda n8n sizden sahip (owner) hesabını oluşturmanızı ister: e-posta, ad ve parola. Bu, n8n kurulumunuzun yöneticisidir; localhost’ta bile güçlü bir parola kullanın.

Basit bir deneme iş akışı

1. Create Workflow düğmesine tıklayın.
2. İş akışı bir düğmeyle çalışsın diye Manual Trigger düğümü ekleyin.
3. Bir HTTP Request düğümü ekleyin ve test API’si gibi genel bir adresi GET yöntemiyle isteyin.
4. Execute Workflow düğmesine tıklayın; her düğümün çıktısı yanında görünür.

Çalıştıktan sonra Manual Trigger’ı Schedule Trigger ile değiştirerek iş akışının belirli bir saatte kendiliğinden çalışmasını sağlayabilirsiniz.

Veriler nerede ve nasıl yedeklenir?

n8n varsayılan olarak .n8n klasöründeki bir SQLite veritabanını kullanır. Docker’da bunların hepsi n8n_data volume’unda durur. Volume’un tamamını yedeklemek için (Linux ve macOS’ta):

docker run --rm -v n8n_data:/data -v "$PWD":/backup alpine tar czf /backup/n8n-backup.tgz -C /data .

Yalnızca iş akışlarına ihtiyacınız varsa konteynerin içinden dışa aktarın:

docker exec -u node n8n n8n export:workflow --all --output=/home/node/.n8n/workflows-backup.json

Şifreleme anahtarı dosyasını (.n8n içindeki config) da saklayın. Bu dosya olmadan kayıtlı kimlik bilgileri yeni bir kurulumda çözülemez.

n8n’i güncellemek

Docker Compose ile:

docker compose pull
docker compose down
docker compose up -d

Yalnızca Docker kullanıyorsanız yeni imajı docker pull n8nio/n8n ile çekin ve konteyneri yeniden çalıştırın. npm ile npm update -g n8n yeterlidir. Büyük bir güncellemeden önce sürüm notlarını okuyun ve yedek alın.

Sık karşılaşılan hatalar

• 5678 portu kullanımda: başka bir program bu portu kullanıyor. Soldaki portu değiştirin, örneğin 127.0.0.1:5679:5678, ve n8n’i http://localhost:5679 adresinden açın.
• Zamanlamalar yanlış saatte çalışıyor: GENERIC_TIMEZONE eksik ya da yanlış.
• Ağdaki başka bir bilgisayardan giriş yapılamıyor: n8n, güvenli çerez gerektirdiği için HTTP üzerinden yalnızca localhost’tan girişe izin verir. Ağdan erişmenin doğru yolu HTTPS’li bir sunucu kurulumudur. Bunu N8N_SECURE_COOKIE=false ile kapatmak yalnızca güvenilir iç ağda test için kabul edilebilir.
• Dışarıdan gelen webhook’lar çalışmıyor: localhost internetten erişilemez. Dış servislerden webhook almak için n8n’in alan adı ve HTTPS ile bir sunucuya kurulması gerekir.
• Ayar dosyası izin hatası: yukarıdaki örneklerdeki gibi N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true ayarlayın.

Güvenlik ipuçları

• n8n portunu yalnızca 127.0.0.1 üzerinde açın. n8n kurumunuzun hesaplarına ve verilerine bağlanır; HTTPS ve güçlü parola olmadan ağdan ya da internetten erişilebilir olmamalıdır.
• Kimlik bilgilerini düğüm metinlerinde değil, yalnızca n8n’in Credentials bölümünde tutun.
• Kurumda gerçek kullanım için n8n’i HTTPS, düzenli yedekleme ve sınırlı erişimle ayrı bir sunucuya kurun.

Localhost’tan gerçek iş otomasyonuna

Localhost öğrenmek ve prototip kurmak için idealdir; ama gece gündüz çalışması, webhook alması ya da iç sistemlere bağlanması gereken bir iş akışı sunucu, alan adı, HTTPS ve yedekleme planı ister. Kurumunuzun tekrarlayan işlerini n8n ya da yapay zekâ ajanlarıyla otomatikleştirmek istiyorsanız yapay zekâ ile iş otomasyonu ve yapay zekâ ajanı geliştirme sayfalarına bakın. n8n’de kullanabileceğiniz yapay zekâ modellerini karşılaştırmak için Claude, ChatGPT, Gemini, Grok ve Codex karşılaştırması makalesini okuyun.