Uygulamanızın bir veritabanı URL’sine ihtiyacı var. Dizüstü bilgisayarınızda yerel bir veritabanıdır, CI’da tek kullanımlıktır ve üretimde yönetilen bir kümedir. Bunlardan herhangi birinin sabit kodlanması, her ortam için kodun değiştirilmesi anlamına gelir. Ortam değişkenleri bunu çözer. Kod DATABASE_URL‘yi okur ve her ortam kendi değerini sağlar.

Bu fikir, dağıtımlar arasında değişen yapılandırmaların ortama ait olduğunu söyleyen On İki Faktörlü Uygulama yönteminin merkezinde yer alır. Aşağıdaki davranışı Windows’ta Python 3.13 ile test ettik. Gösterilen her çıktı bu çalıştırmadan alınmıştır.

Ortam değişkenleri nelerdir?

Çalışan her işlemin, ortamı adı verilen bir dizi adlandırılmış metin değeri vardır. Bilinen örnekler, kabuğa programları nerede bulacağını söyleyen PATH ve HOME veya USERPROFILE‘tür. Kendi uygulamanız APP_PORT, LOG_LEVEL veya DATABASE_URL gibi ayarlar için aynı mekanizmayı kullanabilir.

Ortam değişkenlerini ayarlama

Bunlar yalnızca geçerli terminal oturumu için geçerlidir. Bunları kalıcı kılmak için, bunları ~/.bashrc gibi bir kabuk profiline ekleyin veya Windows’ta sistem ortamı ayarlarını veya setx kullanın. Uygulamalar için, bunları sistem genelinde ayarlamak yerine dağıtım zamanında sağlamak genellikle daha iyidir.

Bunları kod halinde okumak

import os

port = os.environ.get("APP_PORT", "8000")   # default if missing
print(port)                                  # 8000

db = os.environ["DATABASE_URL_MISSING_DEMO"]
# KeyError: 'DATABASE_URL_MISSING_DEMO'

İsteğe bağlı ayarlar için varsayılan değerle .get() kullanın. Uygulamanın onsuz çalışamayacağı ayarlar için KeyError değerini yükselten köşeli parantezleri kullanın. Diğer diller de benzerdir: Node.js’de process.env.APP_PORT, Java’da System.getenv("APP_PORT") ve Go’da os.Getenv("APP_PORT").

Her şey bir dizedir

Bu her dilden insanı yakalar. Bir bağlantı noktası belirledik ve ardından ona “1” ekledik:

os.environ["APP_PORT"] = "8080"
port = os.environ["APP_PORT"]
print(type(port).__name__, repr(port), port + "1")
# str '8080' 80801

os.environ["APP_PORT"] = 8080
# TypeError: str expected, not int

Değer metin olarak geri geldi ve eklenmesi 8081 değil 80801 sonucunu verdi. int(os.environ["APP_PORT"])‘deki gibi açıkça dönüştürün. Boolean’lar daha kötü:

os.environ["DEBUG"] = "false"
print(bool(os.environ["DEBUG"]))   # True

Boş olmayan herhangi bir dize Python’da doğrudur, bu nedenle "false", True oldu. Hata ayıklama modu üretimde açılmış olurdu. Boolean’ları kasıtlı olarak ayrıştırın:

def env_bool(name, default=False):
    value = os.environ.get(name)
    if value is None:
        return default
    return value.strip().lower() in {"1", "true", "yes", "on"}

env_bool("DEBUG")                   # False
env_bool("NOT_SET", default=True)   # True

Süreçler onları nasıl miras alır?

Bir alt süreç, üst ortamının kopyasını alır. Bunu görmek için alt Python işlemlerini başlattık:

child sees: 8080 inherited     # default: full copy of the parent's environment
child sees: 9000 None          # given a custom env: only what we passed
parent sees child var: None    # a child's changes never flow back

Bunu üç pratik ders takip ediyor. Dışa aktardığınız değişkenler, yazmadığınız komut dosyaları da dahil olmak üzere (gizler için önemli olan) başlattığınız her program tarafından görülebilir. Özel bir ortamın geçmesi her şeyin yerini alır, bu nedenle çocuğun ihtiyaç duyduğu her şeyi ekleyin. Ve bir komut dosyası ana kabuğunun değişkenlerini değiştiremez; bu nedenle araçlar sizden bir dosyayı çalıştırmak yerine source yapmanızı ister.

.env dosyaları

Birçok değişkeni elle yazmak sıkıcı olur, bu nedenle çoğu proje yerel geliştirme değerlerini bir .env dosyasında tutar:

# local development only
APP_PORT=8080
DATABASE_URL="postgres://dev:devonly@localhost:5432/shop"
FEATURE_SEARCH=true

Python-dotenv ve Node.js için dotenv gibi kitaplıklar bu dosyayı başlangıçta yükler. Node.js 20.6 ve üzeri, --env-file ile yerel olarak da yüklenebilir. Fikri anlamak için yukarıdaki dosyayı şuna dönüştüren küçük bir ayrıştırıcı yazdık:

{'APP_PORT': '8080',
 'DATABASE_URL': 'postgres://dev:devonly@localhost:5432/shop',
 'FEATURE_SEARCH': 'true'}

Pratikte gerçek bir kütüphane kullanın. 10 satırlık versiyonumuzun göz ardı ettiği alıntılama, kaçış, yorum ve çok satırlı değerleri yönetir. Varsayılan olarak çoğu dotenv yükleyici, önceden ayarlanmış değişkenleri geçersiz kılmazdeğildir, böylece gerçek ortam değerleri dosyanın üzerinde kazanır. Genellikle istediğin budur.

Başlangıçta yapılandırmayı doğrulayın

Eksik bir değişken, açık bir mesajla uygulamayı hemen durdurmalı, bir saat sonra kafa karıştırıcı bir hataya neden olmamalıdır. Yükleme sırasında gerekli ayarları kontrol ettik:

REQUIRED = ["DATABASE_URL", "SECRET_KEY"]

def check_required(env):
    missing = [k for k in REQUIRED if not env.get(k)]
    if missing:
        raise SystemExit(f"Missing required settings: {', '.join(missing)}")

# Missing required settings: SECRET_KEY

Yazılan yapılandırma kitaplıkları daha da ileri gider. Python’daki Pydantic Ayarları, Node.js’deki zod veya envalid ve Java’daki Spring’in yapılandırma özelliklerinin tümü türleri dönüştürür ve her sorunu aynı anda bildirir.

Ortam değişkenleri ve sırlar

Ortam değişkenleri, API anahtarları gibi sırları bir uygulamaya aktarmanın yaygın yoludur ve bunları sabit kodlamaktan çok daha iyidir. Bilmeleri gereken zayıf yönleri var:

• Testimizin gösterdiği gibi çocuk süreçleri onları miras alır.
• Ortamı boşaltan kilitlenme raporlarında, hata ayıklama sayfalarında ve günlüklerde görünebilirler.
• Bazı sistemlerde aynı kullanıcı tarafından çalıştırılan diğer işlemler bunları okuyabilir.

Üretim için birçok ekip, sırları HashiCorp Vault, AWS Secrets Manager, Azure Key Vault veya Google Secret Manager gibi özel bir yöneticide saklar ve bunları çalışma zamanında enjekte eder. Bazıları sırları değişkenler yerine dosyalar olarak birleştirmeyi tercih ediyor. Her iki durumda da, asla günlüklerdeki yapılandırmaları yazdırmayın ve Git’e aktarılmış herhangi bir sırrı geçmişten kaldırdıktan sonra bile döndürün.

Docker ve CI’da

# Docker (not run for this article)
docker run -e APP_PORT=8080 --env-file .env.production myapp

# GitHub Actions (not run for this article)
env:
  APP_PORT: 8080
  API_KEY: ${{ secrets.API_KEY }}

CI platformları sırları şifrelenmiş olarak saklar ve bunları günlüklerde maskeler. Docker dosyasındaki ENV ile Docker görüntülerine sırlar eklemekten kaçının çünkü bunlar görüntü katmanlarında okunabilir durumda kalır. Kurulumların tamamı için Docker Compose eğitimimize ve GitHub Actions CI/CD kılavuzuna bakın.

En iyi uygulamalar

• SHOP_DB_URL gibi bir önekle birlikte anlaşılır, büyük harfli adlar kullanın.
• Tüm yapılandırmaları tek bir modülde okuyun, türleri orada dönüştürün ve başlangıçta doğrulayın.
• Yalnızca hassas olmayan ayarlar için güvenli varsayılanlar sağlayın.
• .env‘i Git’ten uzak tutun ve bir .env.example‘yi koruyun.
• Hassas değerler için üretimde bir gizli dizi yöneticisi kullanın.
• Her değişkeni, türünü ve örnek değerini belgeleyin.

Ortam değişkeni problemlerinde hata ayıklama

Bir uygulama, bir ayar eksikmiş gibi davrandığında şu kontrolleri sırayla gerçekleştirin:

1. Doğru yere ayarlanmış mı? Bir terminal sekmesinde dışa aktarılan bir değişken, diğerinde veya sistem tarafından başlatılan bir hizmette mevcut değil.
2. Uygulama yeniden başlatıldı mı? Çalışan bir işlem, başlatıldığı ortamı korur. Daha sonra bir değişkeni değiştirmenin yeniden başlatmaya kadar hiçbir etkisi yoktur.
3. Ad tam mı? Linux ve macOS’ta adlar büyük/küçük harfe duyarlıdır, dolayısıyla App_Port ve APP_PORT farklı değişkenlerdir. Windows onlara aynı şekilde davranır.
4. Bir .env dosyası onu geçersiz kılıyor mu, yoksa yok sayılıyor mu? Yükleyicinizin mevcut değerleri geçersiz kılıp kılmadığını ve gerçekte hangi dosyayı okuduğunu kontrol edin.
5. Başıboş tırnak işaretleri veya boşluklar var mı? Sonunda boşluk veya fazladan tırnak işaretleri ile kopyalanan bir değer, fark edilmesi zor şekillerde ayrıştırılamayabilir veya eşleşmeyebilir.

Bir sürecin gerçekte ne aldığını görmek için değişken adlarını yazdırın, gizli dizilerin değerlerini asla yazdırmayın. Linux ve macOS’ta printenv mevcut kabuğun ortamını listeler ve PowerShell’de Get-ChildItem Env: de aynısını yapar. Bir konteynerin içinde, env‘ten docker exec‘e kadar çalışmak, konteynerin görünümünü gösterir ve bu genellikle kendi kabuğunuzunkinden farklıdır.

Son bir ipucu: başlangıçta hangi isteğe bağlı ayarların varsayılanlarını kullandığını listeleyen bir satır kaydedin. Hiçbir maliyeti yok ve çoğu kişinin cevabını “bunu neden yapıyor?” hemen sorular.

Son sözler

Ortam değişkenleri basittir ancak birkaç tuzağı gizlerler: Her şey bir iptir, çocuklar bunları miras alır ve sırlar bunlardan sızabilir. Bunları uygulamanıza bir girdi olarak değerlendirin. Bunları tek bir yerde okuyun, erkenden dönüştürüp doğrulayın ve gerçek sırları işlenen dosyalardan uzak tutun.

Sık sorulan sorular

Öğrenmeye devam et