La tua app necessita di un URL di database. Sul tuo laptop è un database locale, in CI uno usa e getta e in produzione un cluster gestito. L’hardcoding di ognuno di essi significa modificare il codice per ogni ambiente. Le variabili ambientali risolvono questo problema. Il codice recita DATABASE_URL e ogni ambiente fornisce il proprio valore.

Questa idea è fondamentale per il metodo dell’app Twelve-Factor, secondo il quale la configurazione che varia tra le distribuzioni appartiene all’ambiente. Abbiamo testato il comportamento seguente con Python 3.13 su Windows. Ogni output mostrato proviene da quella corsa.

Cosa sono le variabili d’ambiente?

Ogni processo in esecuzione ha una serie di valori di testo denominati chiamati il ​​suo ambiente. Esempi familiari sono PATH, che dice alla shell dove trovare i programmi, e HOME o USERPROFILE. La tua app può utilizzare lo stesso meccanismo per impostazioni come APP_PORT, LOG_LEVEL o DATABASE_URL.

Impostazione delle variabili d’ambiente

Questi durano solo per la sessione terminale corrente. Per renderli permanenti, aggiungili a un profilo shell come ~/.bashrc o, su Windows, utilizza le impostazioni dell’ambiente di sistema o setx. Per le applicazioni, in genere è meglio fornirle al momento della distribuzione anziché impostarle a livello di sistema.

Leggendoli in codice

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'

Utilizzare .get() con un valore predefinito per le impostazioni opzionali. Utilizza le parentesi quadre, che sollevano KeyError, per le impostazioni senza le quali l’app non può funzionare. Altri linguaggi sono simili: process.env.APP_PORT in Node.js, System.getenv("APP_PORT") in Java e os.Getenv("APP_PORT") in Go.

Tutto è una corda

Questo cattura persone in ogni lingua. Impostiamo una porta e poi aggiungiamo “1” ad essa:

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

Il valore è tornato come testo e l’aggiunta ha prodotto 80801, non 8081. Convertire esplicitamente, come in int(os.environ["APP_PORT"]). I booleani sono peggio:

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

Qualsiasi stringa non vuota è vera in Python, quindi "false" è diventato True. La modalità debug sarebbe stata attivata in produzione. Analizza deliberatamente i booleani:

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

Come i processi li ereditano

Un processo figlio riceve una copia dell’ambiente genitore. Abbiamo avviato i processi Python figlio per vedere questo:

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

Seguono tre lezioni pratiche. Le variabili che esporti sono visibili a ogni programma che avvii, inclusi gli script che non hai scritto, il che è importante per i segreti. Passare un ambiente personalizzato sostituisce il tutto, quindi includi tutto ciò di cui il bambino ha bisogno. E uno script non può modificare le variabili della shell genitore, motivo per cui gli strumenti ti chiedono di source un file invece di eseguirlo.

file .env

Digitare molte variabili a mano diventa noioso, quindi la maggior parte dei progetti mantiene i valori di sviluppo locale in un file .env:

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

Librerie come python-dotenv e dotenv per Node.js caricano questo file all’avvio. Node.js 20.6 e versioni successive possono anche caricarne uno in modo nativo con --env-file. Per rendere l’idea, abbiamo scritto un piccolo parser, che ha trasformato il file sopra in:

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

Utilizza una vera libreria nella pratica. Gestisce virgolette, escape, commenti e valori su più righe che la nostra versione a 10 righe ignora. Per impostazione predefinita, la maggior parte dei caricatori dotenv non sovrascrive le variabili già impostate, quindi i valori dell’ambiente reale prevalgono sul file. Di solito è quello che vuoi.

Convalidare la configurazione all’avvio

Una variabile mancante dovrebbe arrestare immediatamente l’app con un messaggio chiaro, non causare un errore confuso un’ora dopo. Abbiamo controllato le impostazioni richieste durante il caricamento:

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

Le librerie di configurazione tipizzate vanno oltre. Le impostazioni Pydantic in Python, zod o envalid in Node.js e le proprietà di configurazione di Spring in Java convertono tutti i tipi e segnalano ogni problema contemporaneamente.

Variabili d’ambiente e segreti

Le variabili di ambiente rappresentano il modo comune per passare segreti come le chiavi API a un’app e sono molto meglio che codificarle in modo rigido. Hanno dei punti deboli da conoscere:

• I processi figli li ereditano, come ha dimostrato il nostro test.
• Possono apparire nei rapporti sugli arresti anomali, nelle pagine di debug e nei registri che scaricano l’ambiente.
• Su alcuni sistemi, altri processi eseguiti dallo stesso utente possono leggerli.

Per la produzione, molti team mantengono i segreti in un gestore dedicato, come HashiCorp Vault, AWS Secrets Manager, Azure Key Vault o Google Secret Manager, e li inseriscono in fase di runtime. Alcuni preferiscono montare i segreti come file anziché come variabili. In ogni caso, non stampare mai la configurazione nei log e ruotare qualsiasi segreto che sia mai stato impegnato in Git, anche dopo averlo rimosso dalla cronologia.

In Docker e 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 }}

Le piattaforme CI archiviano i segreti crittografati e li mascherano nei log. Evitare di inserire segreti nelle immagini Docker con ENV nel Dockerfile, perché rimangono leggibili nei livelli dell’immagine. Consulta il nostro tutorial su Docker Compose e la guida CI/CD di GitHub Actions per le configurazioni complete.

Migliori pratiche

• Utilizzare nomi chiari e maiuscoli con un prefisso, ad esempio SHOP_DB_URL.
• Leggi tutta la configurazione in un modulo, converti i tipi lì e convalida all’avvio.
• Fornire impostazioni predefinite sicure solo per le impostazioni non sensibili.
• Mantieni .env fuori da Git e mantieni un .env.example.
• Utilizzare un gestore dei segreti in produzione per i valori sensibili.
• Documenta ogni variabile, il suo tipo e un valore di esempio.

Debug dei problemi relativi alle variabili di ambiente

Quando un’app si comporta come se mancasse un’impostazione, esegui questi controlli in ordine:

1. È impostata nel posto giusto? Una variabile esportata in una scheda del terminale non esiste in un’altra o in un servizio avviato dal sistema.
2. L’app è stata riavviata? Un processo in esecuzione mantiene l’ambiente con cui è stato avviato. La modifica successiva di una variabile non ha alcun effetto fino al riavvio.
3. Il nome è esatto? I nomi fanno distinzione tra maiuscole e minuscole su Linux e macOS, quindi App_Port e APP_PORT sono variabili diverse. Windows li tratta allo stesso modo.
4. Un file .env lo sovrascrive o viene ignorato? Controlla se il tuo caricatore sovrascrive i valori esistenti e quale file legge effettivamente.
5. Sono presenti virgolette o spazi? Un valore copiato con uno spazio finale o virgolette extra può non essere analizzato o non trovare una corrispondenza in modi difficili da individuare.

Per vedere cosa ha realmente ricevuto un processo, stampa i nomi delle variabili, mai i valori dei segreti. In Linux e macOS, printenv elenca l’ambiente della shell corrente e in PowerShell Get-ChildItem Env: fa lo stesso. All’interno di un contenitore, l’esecuzione da env a docker exec mostra la vista del contenitore, che spesso è diversa da quella della propria shell.

Un ultimo consiglio: registra una riga all’avvio che elenca quali impostazioni opzionali utilizzano i valori predefiniti. Non costa nulla e la maggior parte delle persone risponde “perché lo fa?” domande subito.

Considerazioni finali

Le variabili d’ambiente sono semplici, ma nascondono alcune trappole: tutto è una stringa, i bambini le ereditano e i segreti possono trapelare attraverso di esse. Trattali come input per la tua app. Leggili in un unico posto, convertili e convalidali in anticipo e mantieni i veri segreti lontani dai file che vengono sottoposti a commit.

Domande frequenti

Continua a imparare