Aplikasi Anda memerlukan URL database. Di laptop Anda, ini adalah database lokal, di CI adalah database sekali pakai, dan dalam produksi, cluster terkelola. Mengkodekan salah satu dari mereka berarti mengubah kode untuk setiap lingkungan. Variabel lingkungan menyelesaikan masalah ini. Kodenya berbunyi DATABASE_URL, dan setiap lingkungan memberikan nilainya sendiri.

Ide ini merupakan inti dari metode Aplikasi Dua Belas Faktor, yang menyatakan bahwa konfigurasi yang bervariasi antar penerapan di lingkungan. Kami menguji perilaku di bawah ini dengan Python 3.13 di Windows. Setiap keluaran yang ditampilkan berasal dari proses tersebut.

Apa yang dimaksud dengan variabel lingkungan?

Setiap proses yang berjalan memiliki sekumpulan nilai teks bernama yang disebut lingkungannya. Contoh yang lazim adalah PATH, yang memberi tahu shell di mana menemukan program, dan HOME atau USERPROFILE. Aplikasi Anda sendiri dapat menggunakan mekanisme yang sama untuk pengaturan seperti APP_PORT, LOG_LEVEL atau DATABASE_URL.

Mengatur variabel lingkungan

Ini hanya berlangsung untuk sesi terminal saat ini. Untuk menjadikannya permanen, tambahkan ke profil shell seperti ~/.bashrc, atau, di Windows, gunakan pengaturan lingkungan sistem atau setx. Untuk aplikasi, biasanya lebih baik menyediakannya pada waktu penerapan daripada mengaturnya di seluruh sistem.

Membacanya dalam kode

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'

Gunakan .get() dengan default untuk pengaturan opsional. Gunakan tanda kurung siku, yang memunculkan KeyError, untuk pengaturan yang tanpanya aplikasi tidak dapat berfungsi. Bahasa lain serupa: process.env.APP_PORT di Node.js, System.getenv("APP_PORT") di Java, dan os.Getenv("APP_PORT") di Go.

Semuanya adalah string

Ini menangkap orang-orang dalam setiap bahasa. Kami menetapkan port dan kemudian menambahkan “1” ke dalamnya:

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

Nilainya kembali sebagai teks, dan penambahan menghasilkan 80801, bukan 8081. Konversi secara eksplisit, seperti pada int(os.environ["APP_PORT"]). Boolean lebih buruk:

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

String yang tidak kosong apa pun benar dalam Python, jadi "false" menjadi True. Mode debug akan diaktifkan dalam produksi. Parsing boolean dengan sengaja:

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

Bagaimana proses mewarisinya

Proses anak menerima salinan dari lingkungan induknya. Kami memulai proses Python anak untuk melihat ini:

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

Tiga pelajaran praktis menyusul. Variabel yang Anda ekspor terlihat oleh setiap program yang Anda luncurkan, termasuk skrip yang tidak Anda tulis, yang penting bagi rahasia. Melewati lingkungan khusus menggantikan semuanya, jadi sertakan apa pun yang dibutuhkan anak. Dan skrip tidak dapat mengubah variabel shell induknya, itulah sebabnya alat meminta Anda source file alih-alih menjalankannya.

file .env

Mengetik banyak variabel dengan tangan akan membosankan, sehingga sebagian besar proyek menyimpan nilai pengembangan lokal dalam file .env:

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

Perpustakaan seperti python-dotenv, dan dotenv untuk Node.js, memuat file ini saat startup. Node.js 20.6 dan yang lebih baru juga dapat memuatnya secara asli dengan --env-file. Untuk melihat idenya, kami menulis parser kecil, yang mengubah file di atas menjadi:

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

Gunakan perpustakaan nyata dalam praktiknya. Ini menangani kutipan, pelolosan, komentar, dan nilai multi-baris yang diabaikan oleh versi 10 baris kami. Secara default, sebagian besar pemuat dotenv tidak mengganti variabel yang telah disetel, sehingga nilai lingkungan nyata memenangkan file. Biasanya itulah yang Anda inginkan.

Validasi konfigurasi saat startup

Variabel yang hilang harus segera menghentikan aplikasi dengan pesan yang jelas, tidak menyebabkan kesalahan yang membingungkan satu jam kemudian. Kami memeriksa pengaturan yang diperlukan saat memuat:

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

Perpustakaan konfigurasi yang diketik melangkah lebih jauh. Pengaturan Pydantic dengan Python, zod atau envalid di Node.js, dan properti konfigurasi Spring di Java semuanya mengonversi tipe dan melaporkan setiap masalah sekaligus.

Variabel dan rahasia lingkungan

Variabel lingkungan adalah cara umum untuk meneruskan rahasia seperti kunci API ke aplikasi, dan variabel ini jauh lebih baik daripada melakukan hardcoding. Mereka memang memiliki kelemahan yang perlu diketahui:

• Proses anak mewarisinya, seperti yang ditunjukkan pengujian kami.
• Mereka dapat muncul di laporan kerusakan, halaman debug, dan log yang membuang lingkungan.
• Pada beberapa sistem, proses lain yang dijalankan oleh pengguna yang sama dapat membacanya.

Untuk produksi, banyak tim menyimpan rahasia di manajer khusus, seperti HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, atau Google Secret Manager, dan memasukkannya saat runtime. Beberapa lebih memilih memasang rahasia sebagai file daripada variabel. Apa pun yang terjadi, jangan pernah mencetak konfigurasi di log, dan merotasi rahasia apa pun yang pernah dikomit ke Git, bahkan setelah Anda menghapusnya dari riwayat.

Di Docker dan CI

# 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 }}

Platform CI menyimpan rahasia yang dienkripsi dan menyembunyikannya dalam log. Hindari memasukkan rahasia ke dalam image Docker dengan ENV di Dockerfile, karena rahasia tersebut tetap dapat dibaca di lapisan image. Lihat tutorial Docker Compose kami dan panduan CI/CD Tindakan GitHub untuk pengaturan lengkap.

Praktik terbaik

• Gunakan nama yang jelas dan huruf besar dengan awalan, misalnya SHOP_DB_URL.
• Baca semua konfigurasi dalam satu modul, konversi tipe di sana, dan validasi saat startup.
• Berikan default yang aman hanya untuk pengaturan yang tidak sensitif.
• Jauhkan .env dari Git dan pertahankan .env.example.
• Gunakan manajer rahasia dalam produksi untuk nilai-nilai sensitif.
• Dokumentasikan setiap variabel, tipenya, dan contoh nilai.

Men-debug masalah variabel lingkungan

Saat aplikasi berperilaku seolah-olah ada pengaturan yang hilang, lakukan pemeriksaan berikut secara berurutan:

1. Apakah sudah diatur di tempat yang tepat? Variabel yang diekspor di satu tab terminal tidak ada di tab terminal lain, atau di layanan yang dimulai oleh sistem.
2. Apakah aplikasi dimulai ulang? Proses yang berjalan mempertahankan lingkungan tempat aplikasi dimulai. Mengubah variabel setelahnya tidak berpengaruh hingga restart.
3. Apakah namanya tepat? Nama peka huruf besar-kecil di Linux dan macOS, jadi App_Port dan APP_PORT merupakan variabel yang berbeda. Windows memperlakukannya sama.
4. Apakah file .env menimpanya, atau diabaikan? Periksa apakah loader Anda mengabaikan nilai yang ada, dan file mana yang benar-benar dibaca.
5. Apakah ada tanda kutip atau spasi yang menyimpang? Nilai yang disalin dengan spasi tambahan atau tanda kutip tambahan bisa gagal diurai, atau gagal dicocokkan, sehingga sulit dikenali.

Untuk melihat proses yang benar-benar diterima, cetak nama variabel, bukan nilai rahasianya. Di Linux dan macOS, printenv mencantumkan lingkungan shell saat ini, dan di PowerShell Get-ChildItem Env: melakukan hal yang sama. Di dalam container, menjalankan env hingga docker exec menampilkan tampilan container, yang sering kali berbeda dari tampilan shell Anda.

Tip terakhir: catat satu baris saat startup yang mencantumkan pengaturan opsional mana yang menggunakan defaultnya. Tidak ada biaya apa pun, dan sebagian besar menjawab “mengapa melakukan hal itu?” pertanyaan langsung.

Penutup

Variabel lingkungan itu sederhana, tetapi menyembunyikan beberapa jebakan: semuanya adalah string, turunan mewarisinya, dan rahasia dapat bocor melaluinya. Perlakukan mereka sebagai masukan untuk aplikasi Anda. Bacalah di satu tempat, konversikan dan validasi lebih awal, dan simpan rahasia nyata dari file yang dikomit.

Pertanyaan yang sering diajukan

Teruslah belajar