Node-RED, Docker ve güvenli bir editörle nasıl kurulur

Node-RED, olay güdümlü uygulamalar için düşük kodlu (low-code) bir programlama aracıdır. Tarayıcı tabanlı akış editöründe düğümleri birbirine bağlayarak cihazları, API'leri ve çevrim içi servisleri birleştirirsiniz; bu yüzden IoT, ev otomasyonu, veri toplama ve küçük entegrasyonlar için çok kullanılır. Akışlar JSON olarak saklanır ve Node.js üzerinde çalışır.

Bu rehber Node-RED'i, Node-RED'in konteynerler için belgelediği yöntem olan resmi nodered/node-red Docker imajından çalıştırır. Tüm verileri tek bir klasörde tutar, editörü yalnızca 127.0.0.1 üzerinde yayınlar, bcrypt ile hash'lenmiş bir parolayla korur ve HTTPS için önüne Caddy koyarsınız. Ayrıca ek düğümler kurar, isteğe bağlı Git tabanlı projeler özelliğini açar, yedekleme ve güncellemeyi ayarlarsınız. Node-RED'i doğrudan sunucuda çalıştırmayı tercih ederseniz kısa bir bölüm resmi Linux kurulum betiğini açıklar.

Adım 1 — Veri klasörünü oluşturun

Node-RED akışları, kimlik bilgilerini, ayarları ve kurulu düğümleri konteyner içindeki /data klasöründe saklar. settings.js dosyasını kolayca düzenleyip yedekleyebilmek için bu klasörü sunucudaki bir klasöre bağlayın. Konteyner UID'si 1000 olan node-red kullanıcısıyla çalıştığı için klasörün sahibi UID 1000 olmalıdır:

sudo mkdir -p /opt/node-red/data
sudo chown $USER:$USER /opt/node-red
sudo chown -R 1000:1000 /opt/node-red/data
cd /opt/node-red

Adım 2 — Node-RED'i Docker Compose ile başlatın

/opt/node-red/compose.yaml dosyasını oluşturun. Dosya resmi imajı kullanır, 1880 numaralı portu yalnızca loopback adresinde yayınlar ve inject düğümlerinin ve zaman fonksiyonlarının kullandığı saat dilimini ayarlar:

services:
  node-red:
    image: nodered/node-red:latest
    restart: unless-stopped
    environment:
      - TZ=Europe/Istanbul
    ports:
      - "127.0.0.1:1880:1880"
    volumes:
      - ./data:/data

Europe/Istanbul değerini kendi IANA saat diliminizle değiştirin. latest etiketi varsayılan Node.js sürümündeki en yeni sürümü izler; imaj ayrıca Python ve derleme araçları içermeyen -minimal varyantları, latest-22 gibi Node.js sürümüne özel etiketler ve Alpine üzerinde derlenemeyen düğümler için Debian tabanlı latest-debian imajıyla gelir. Bir sürümü sabitlemek için bunun yerine Docker Hub'daki bir sürüm etiketini kullanın, örneğin nodered/node-red:5.0.8.

Konteyneri başlatın ve loga bakın:

docker compose up -d
docker compose logs node-red

Settings file : /data/settings.js, User directory : /data satırlarını ve sunucunun 1880 numaralı portta çalışmaya başladığını bildiren bir satırı görmelisiniz. Node-RED ilk açılışta varsayılan bir settings.js dosyasını /data içine kopyalar; bu dosyayı bir sonraki adımda düzenleyeceksiniz. Editörü sunucudan kontrol edin:

curl -I http://127.0.0.1:1880

Yanıt HTTP/1.1 200 OK olmalıdır.

Adım 3 — Editörü parolayla koruyun

Node-RED belgeleri, editörün varsayılan olarak güvenli olmadığını açıkça söyler: ona erişebilen herkes akış dağıtabilir ve akışlar komut çalıştırabilir. Editör çevrim içi olmadan önce adminAuth ayarını açın.

Önce parolanızın bcrypt hash'ini oluşturun. İmaj Node-RED yönetim aracını içerdiği için sunucuda Node.js'e ihtiyacınız yoktur:

docker compose exec node-red npx node-red admin hash-pw

İstendiğinde parolayı iki kez yazın ve ekrana yazdırılan hash'i kopyalayın. Ardından settings.js dosyasını açın:

sudo nano /opt/node-red/data/settings.js

Security bölümündeki yorum satırı haline getirilmiş //adminAuth bloğunu bulun ve aşağıdakiyle değiştirin; parola değeri olarak kendi hash'inizi yapıştırın. permissions: "*" tam erişim verir; permissions: "read" ile tanımlanan ikinci bir kullanıcı yalnızca okuma görünümü alır:

    adminAuth: {
        type: "credentials",
        users: [{
            username: "nodered-admin",
            password: "paste-the-bcrypt-hash-here",
            permissions: "*"
        }]
    },

Node-RED'i yeniden başlatın ve yönetim API'sinin artık kimlik bilgisi istediğini doğrulayın:

docker compose restart node-red
curl -s http://127.0.0.1:1880/auth/login

Yanıt artık "type":"credentials" içerir. Node-RED başlamıyorsa genellikle settings.js içindeki eksik bir virgül nedendir; docker compose logs node-red ilgili satırı gösterir. Erişim token'ları varsayılan olarak yedi gün sonra sona erer; bunu değiştirmek için settings.js içinde sessionExpiryTime değerini (saniye cinsinden) ayarlayın.

Adım 4 — HTTP uç noktalarını koruyun (isteğe bağlı)

HTTP In düğümlerini kullanan akışlar kendi adreslerini sunar ve editör kilitli olsa bile bu adresler herkese açık kalır. Herkese açık olmamaları gerekiyorsa aynı bcrypt hash biçimini kullanan httpNodeAuth ayarını yapın. Adım 3'teki komutla ayrı bir hash üretin ve bu satırı settings.js dosyasına ekleyin:

    httpNodeAuth: {user:"api-user", pass:"paste-the-bcrypt-hash-here"},

httpStatic üzerinden sunulan statik dosyalar da aynı şekilde httpStaticAuth ile korunabilir. settings.js dosyasındaki her değişiklikten sonra konteyneri yeniden başlatın. Başka servislerin çağırdığı herkese açık webhook'lar için httpNodeAuth ayarını kapalı bırakın ve bunun yerine akış içinde gizli bir başlığı veya token'ı doğrulayın.

Adım 5 — Node-RED'i Caddy ile HTTPS üzerinden yayınlayın

/etc/caddy/Caddyfile dosyasına bir site bloğu ekleyin. Caddy, editörün canlı güncellemeler için kullandığı WebSocket bağlantısını ek ayar gerektirmeden iletir:

nodered.example.com {
    reverse_proxy 127.0.0.1:1880
}

Caddy'yi yeniden yükleyin, güvenlik duvarında yalnızca SSH ve web trafiğine izin verin ve sonucu test edin:

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
curl -I https://nodered.example.com

Geçerli bir sertifikayla HTTP/2 200 almalısınız. Adresi tarayıcıda açın ve Adım 3'teki kullanıcıyla giriş yapın. Konteyner yalnızca 127.0.0.1 üzerinde dinlediği için 1880 numaralı port internete kapalı kalır. Bunun yerine Nginx kullanıyorsanız proxy, WebSocket için Upgrade ve Connection başlıklarını iletmelidir; Nginx ve Certbot rehberine bakın.

Adım 6 — Ek düğümler kurun

En kolay yol Palette Manager'dır: ana menüyü açın, Manage palette seçeneğini seçin, Install sekmesine geçin ve bir modül arayın. flows.nodered.org adresindeki akış kütüphanesi mevcut düğümleri listeler. Paketler /data içine kurulduğu için konteyner güncellemelerinden etkilenmez.

Komut satırından konteyner içinde /data klasöründe npm install çalıştırın ve yeni düğümlerin yüklenmesi için Node-RED'i yeniden başlatın:

cd /opt/node-red
docker compose exec node-red bash -c "cd /data && npm install node-red-node-email"
docker compose restart node-red

-minimal imaj varyantlarında Python ve derleme araçları yoktur; yerel kod derleyen düğümleri kuramazlar. Böyle düğümlere ihtiyacınız varsa varsayılan veya -debian imajını kullanın.

Adım 7 — Git ile projeleri açın (isteğe bağlı)

Projeler özelliği akışlarınızı bir Git deposuna dönüştürür: değişiklikleri editörün History sekmesinden commit eder ve kendi sunucunuzdaki bir Gitea gibi uzak bir depoya gönderirsiniz. Resmi imaj bu özelliğin ihtiyaç duyduğu git ve ssh-keygen araçlarını zaten içerir. Özelliği bir ortam değişkeniyle açın:

    environment:
      - TZ=Europe/Istanbul
      - NODE_RED_ENABLE_PROJECTS=true

Değişikliği uygulamak için docker compose up -d çalıştırın. Editör ardından ilk projenizi oluşturmayı önerir. Kimlik bilgisi şifreleme anahtarı istendiğinde güçlü bir anahtar seçin ve parola yöneticinizde saklayın: anahtar depoya kaydedilmez ve projeyi klonlayan herkesin kimlik bilgilerini çözebilmesi için bu anahtara ihtiyacı vardır.

Alternatif: Docker olmadan kurulum

Node-RED, Ubuntu ve Debian dahil Debian tabanlı sistemler için resmi bir kurulum betiği de sunar. Betik mevcut bir Node-RED kurulumunu kaldırır, Node.js 20 veya daha yeni bir sürümün bulunduğundan emin olur (yoksa NodeSource'tan Node.js 22 LTS kurar), en yeni Node-RED'i npm ile kurar ve onu node-red-start, node-red-stop ve node-red-log gibi yardımcı komutlarla birlikte nodered systemd servisi olarak ayarlar. Bu yol, akışların seri cihazlar gibi donanımlara doğrudan erişmesi gerektiğinde kullanışlıdır.

Betiği indirin, okuyun, ardından normal sudo kullanıcınızla çalıştırın. --help seçenekleri listeler:

sudo apt install build-essential git curl
curl -fsSL https://github.com/node-red/linux-installers/releases/latest/download/install-update-nodered-deb -o install-nodered.sh
less install-nodered.sh
bash install-nodered.sh
sudo systemctl enable --now nodered.service

Resmi tek satırlık eşdeğeri aynı dosyayı doğrudan bash'e aktarır. Bu yöntemde kullanıcı klasörü ~/.node-red olur, node-red admin hash-pw doğrudan sunucuda çalışır ve Node-RED varsayılan olarak tüm arayüzlerde dinler. 1880 numaralı porta yalnızca Caddy'nin erişebilmesi için ~/.node-red/settings.js içinde uiHost: "127.0.0.1", ayarını yapın, adminAuth ayarını Adım 3'teki gibi yapılandırın ve node-red-restart ile yeniden başlatın. Yükseltmek için betiği yeniden çalıştırın.

Yedekleme ve geri yükleme

Node-RED'in ihtiyaç duyduğu her şey /opt/node-red/data içindedir: flows.json, şifreli kimlik bilgisi dosyası flows_cred.json, settings.js, kurulu düğümlerin listesini içeren package.json, düğümlerin kendisi ve Node-RED'in kimlik bilgilerini şifrelemek için ürettiği anahtar. Gizli dosyalar dahil klasörün tamamını compose.yaml ile birlikte arşivleyin:

sudo mkdir -p /opt/backups
sudo tar czf /opt/backups/node-red-$(date +%F).tar.gz -C /opt/node-red data compose.yaml
sudo chmod 600 /opt/backups/node-red-*.tar.gz

Arşiv Node-RED çalışırken alınabilir. Arşivi başka bir makineye veya nesne depolamaya kopyalayın; aynı sunucuda kalan bir yedek sunucuyla birlikte kaybolur.

Geri yüklemek için konteyneri durdurun, klasörü değiştirin ve sahipliği düzeltin:

cd /opt/node-red
docker compose down
sudo rm -rf /opt/node-red/data
sudo tar xzf /opt/backups/node-red-2026-10-09.tar.gz -C /opt/node-red
sudo chown -R 1000:1000 /opt/node-red/data
docker compose up -d

Üretilen kimlik bilgisi anahtarı olmadan akışlar yüklenir ama kayıtlı tüm kimlik bilgileri kaybolur. Akışları sunucular arasında sık taşıyorsanız settings.js içinde kendi credentialSecret değerinizi belirleyin ve parola yöneticinizde saklayın.

Node-RED güncelleme

Yeni bir ana sürümden önce Node-RED blogundaki sürüm notlarını okuyun; örneğin Node-RED 5, Docker imajının zaten sağladığı Node.js 22 veya daha yeni bir sürüm gerektirir. Veri klasörünü yedekleyin, ardından yeni imajı çekip konteyneri yeniden oluşturun:

cd /opt/node-red
docker compose pull
docker compose up -d
docker compose logs --tail=20 node-red

Log yeni Node-RED ve Node.js sürümlerini gösterir. Bir sürüm etiketi sabitlediyseniz önce compose.yaml içinde değiştirin. Kurulu düğümler /data içinde kalır; onları eski modüllerde bir güncelleme düğmesi gösteren Manage palette ekranından güncelleyin. Yerel kod içeren bir düğüm Node.js yükseltmesinden sonra hata verirse docker compose exec node-red bash -c "cd /data && npm rebuild" ile yeniden derleyin.

Sorun giderme

/data üzerinde Error: EACCES: permission denied

Sunucudaki klasörün sahibi, konteynerin içindeki kullanıcı olan UID 1000 değil. sudo chown -R 1000:1000 /opt/node-red/data çalıştırın ve konteyneri yeniden başlatın. Bu durum genellikle bir yedeği root olarak geri yükledikten veya dosyaları sudo cp ile kopyaladıktan sonra ortaya çıkar.

Editör Lost connection to server gösteriyor

Tarayıcı Node-RED ile WebSocket bağlantısını açık tutamıyor. Caddy WebSocket'leri kendiliğinden işler; Nginx'te Upgrade ve Connection başlıklarını iletmeli ve proxy bağlantısı için HTTP/1.1 kullanmalısınız. Tarayıcı ile sunucu arasındaki CDN veya güvenlik duvarı gibi bir katmanın WebSocket'leri engellemediğini de kontrol edin.

Editör parolasını unuttum

docker compose exec node-red npx node-red admin hash-pw ile yeni bir hash üretin, /opt/node-red/data/settings.js içindeki password değerini değiştirin ve docker compose restart node-red çalıştırın. Akışlar ve kimlik bilgileri bundan etkilenmez.

Bir düğüm palette üzerinden kurulamıyor

Hatayı docker compose logs node-red içinde okuyun. Yerel bileşenleri olan düğümler, -minimal imajlarda bulunmayan Python ve derleme araçlarına ihtiyaç duyar; varsayılan veya -debian etiketine geçin. Düğümün Node-RED ve Node.js sürümlerinizi desteklediğini de kontrol edin.

Bir akış dağıtıldıktan sonra Node-RED açılışta çöküyor

Hatalı bir akış veya düğüm çalışma ortamının başlamasını engelleyebilir. environment listesine NODE_RED_ENABLE_SAFE_MODE=true ekleyin ve docker compose up -d çalıştırın: Node-RED akışları çalıştırmadan başlar, böylece sorunu editörde düzeltebilir veya silebilirsiniz. Ardından değişkeni yeniden kaldırın.

Sonraki adımlar

• API odaklı iş akışı otomasyonu için Node-RED'i n8n ile karşılaştırın.
• Node-RED'i Docker'da Home Assistant ile akıllı evinize bağlayın.
• Otomasyon altyapınız için sunucuları Node-RED hosting sayfasında bulun.
• Akış tasarımı, yönetim API'si ve güvenlik ayarları için resmi Node-RED belgelerini okuyun.