Node.js Ortam Değişkenleri Yönetimi (.env)
Ortam değişkenleri (.env) nedir? API anahtarları (Stripe, AWS vb.), veritabanı şifreleri (PostgreSQL, MongoDB) ve JWT token secret'ları gibi hassas verilerin, kaynak koddan (source code) ayrı bir yerde güvenle saklanmasını sağlayan anahtar-değer (key-value) yapılarıdır.
Node.js ve Express.js uygulamalarında güvenliğin 1. kuralı, bu verileri GitHub gibi versiyon kontrol sistemlerine yüklememektir. Flyway, bu hassas konfigürasyonları tamamen şifrelenmiş bir altyapıda, doğrudan panel üzerinden yönetmenizi sağlar.
İçindekiler (Bu Rehberde Neler Öğreneceksiniz?)
1. Ön Koşullar (Prerequisites)
Node.js ortam değişkenlerinizi yapılandırmadan önce aşağıdakilere sahip olduğunuzdan emin olun:
- ✅ Flyway üzerinde oluşturulmuş ve GitHub ile bağlanmış bir projeniz olmalı.
- ✅ Projenizde
dotenv(veya NestJS için@nestjs/config) paketi kurulu olmalıdır (Lokal geliştirme için).
2. GitHub Güvenliği (.gitignore)
En kritik güvenlik açığı, lokalde oluşturduğunuz .env dosyasının yanlışlıkla GitHub'a yüklenmesidir. Bir bot saniyeler içinde herkese açık deponuzu tarayıp veritabanı şifrenizi bulabilir.
Mutlaka projenizin kök dizinindeki .gitignore dosyasına .env satırını ekleyin. Böylece şifreleriniz GitHub'a gitmez.
3. Flyway Panelinden Değişken Ekleme
Dosyanızı GitHub'a atmadığınız için, uygulamanız production ortamında şifrelere ihtiyaç duyacaktır. Bunları Flyway paneli üzerinden güvenle ekleriz.
4. Kod İçinde Kullanım (Ana Kurallar)
Panel üzerinden eklediğiniz tüm değişkenler, projeniz derlenirken sunucu ortamına aktarılır. Node.js kodunuzun içerisinde bu değişkenlere process.env objesi üzerinden erişebilirsiniz.
Şifreleri doğrudan kodun içine yazmak tehlikelidir ve kod her değiştiğinde deploy gerektirir.
Değerleri çevresel değişkenlerden okuyun.
const jwtSecret = process.env.JWT_SECRET;
const port = process.env.PORT || 3000;
5. Değişken Okuma Hataları (Debugging)
Uygulamanız canlıya alındığında veritabanı bağlantısı sağlayamıyorsa, bunun sebebi %90 oranında eksik veya yanlış girilmiş bir ortam değişkenidir.
- Flyway paneline gidin ve Logs sekmesine tıklayın.
- Hata kaydında
"Cannot read property of undefined"veya"Invalid connection string"görüyorsanız, ortam değişkeninizin adı ile koddaki adın (örn:DB_URLvsDATABASE_URL) birebir aynı olduğuna emin olun. - Yeni bir ortam değişkeni ekledikten sonra uygulamanızı Yeniden Dağıt (Redeploy) yapmanız gerekebilir.
6. Sorun Giderme ve Sık Sorulan Sorular
Sık Sorulan Sorular (Kavramsal)
.env dosyamı Flyway panelinden nereye yükleyeceğim?
Flyway, dosya yüklemek yerine Key-Value şeklinde doğrudan paneli üzerinden verileri güvenle eklemenizi sağlar. "Environment Variables" sekmesinden tek tek ekleyebilirsiniz.
Ortam değişkenleri anında güncellenir mi?
Bir değişken eklediğinizde veya sildiğinizde, değişikliklerin Node.js process'ine yansıması için uygulamanın yeniden başlatılması (Restart/Redeploy) gerekir.
Sorun Giderme Tablosu (Hatalar ve Çözümler)
| Hata Mesajı / Belirti | Olası Neden | Çözüm |
|---|---|---|
| process.env.VAR_NAME undefined dönüyor | Panelden değişken eklenmemiş veya yazım hatası var. | Panelden değişken adını (büyük/küçük harf duyarlı) kontrol edin ve redeploy yapın. |
| Veritabanı bağlantısı reddedildi (Connection Refused) | DATABASE_URL ortam değişkenindeki IP adresi Flyway'e izin vermiyor olabilir. |
Veritabanınızın güvenlik duvarından dış bağlantılara (veya `0.0.0.0/0` IP'sine) izin verin. |
7. İlgili Makaleler
Node.js (Express) Deploy →
Express projelerinizi ve ortam değişkenlerinizi canlıya alın.
NestJS Projelerini Deploy Edin →
NestJS içindeki hassas verileri config module ile bağlayın.
Hazırsınız! 🚀
Değişkenlerinizi güvenle yönettiğinize göre, uygulamanız artık üretime hazır. Loglarınızı takip ederek anında özel alan adınızda (Domain) servise başlayabilirsiniz.