Gestione delle Variabili d'Ambiente e Configurazione nelle Web App

Inserire direttamente nel codice sorgente (hardcoding) credenziali di database, chiavi API o flag di funzionalità è uno degli errori più frequenti e rischiosi nello sviluppo moderno. Le variabili d'ambiente permettono di separare drasticamente la configurazione dal codice, consentendo di distribuire lo stesso identico software in ambienti di sviluppo, staging e produzione semplicemente cambiando i parametri esterni.

Il Principio delle 12-Factor App

La metodologia 12-Factor App, standard de facto per la creazione di applicazioni cloud-native, stabilisce che la configurazione debba risiedere interamente nell'ambiente e mai nel codice. Questo approccio garantisce che:

• URL dei database, secret delle API e token non vengano mai caricati sui sistemi di versionamento (Git).
• Lo stesso pacchetto software sia eseguibile ovunque; cambia solo il contesto di esecuzione.
• La configurazione venga iniettata dinamicamente tramite il sistema operativo o il container a runtime.

Utilizzare i file .env

# Configurazione Database
DATABASE_URL=postgres://user:password@localhost:5432/mio_db_dev
DATABASE_POOL_SIZE=10

# Chiavi API di Terze Parti
STRIPE_SECRET_KEY=sk_test_abc123
SENDGRID_API_KEY=SG.xxxxx

# Impostazioni Applicazione
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000

# Feature Flags (Interruttori Funzionalità)
ENABLE_NEW_CHECKOUT=true
ENABLE_DARK_MODE=false

Come Leggere le Variabili nel Codice

// Carica il file .env in fase di sviluppo
import 'dotenv/config';

// Accesso alle variabili di sistema
const dbUrl = process.env.DATABASE_URL;
const port = parseInt(process.env.PORT || '3000', 10);
const isDev = process.env.NODE_ENV === 'development';

// Validazione obbligatoria all'avvio
const required = ['DATABASE_URL', 'STRIPE_SECRET_KEY'];
for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`Variabile d'ambiente mancante: ${key}`);
  }
}

// Funzioni native PHP
$dbUrl = getenv('DATABASE_URL');
$debug = getenv('APP_DEBUG') === 'true';

// Con vlucas/phpdotenv (via Composer)
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$dotenv->required(['DATABASE_URL', 'APP_KEY'])->notEmpty();

// Accesso tramite superglobale $_ENV
$apiKey = $_ENV['STRIPE_SECRET_KEY'];

Regola d'Oro: Il file .gitignore

# NON caricare mai questi file sul repository
.env
.env.local
.env.production
.env.staging

# Carica invece un template (senza dati sensibili)
# .env.example

È buona norma creare un file .env.example che contenga tutte le chiavi necessarie ma con valori fittizi. Questo serve ai nuovi sviluppatori per capire quali variabili devono configurare localmente per far girare il progetto.

DATABASE_URL=postgres://utente:password@host:porto/nome_db
STRIPE_SECRET_KEY=inserisci_qui_la_tua_chiave_test
NODE_ENV=development
PORT=3000

Configurazioni per Ambiente

• Development: Modalità debug attiva, log verbosi, database locale e chiavi API di test.
• Staging: Ambiente speculare alla produzione per test finali, chiavi sandbox.
• Production: Massima sicurezza, log minimi, database scalabile, chiavi API reali e obbligo di HTTPS.

Gestione dei Secret in Produzione

In produzione, l'uso di semplici file .env potrebbe non essere sufficiente. È consigliabile adottare soluzioni di Secrets Management dedicate:

• Cloud Provider: AWS Secrets Manager, Google Secret Manager o Azure Key Vault.
• HashiCorp Vault: Uno strumento centralizzato per la gestione sicura di token, password e certificati.
• Pipeline CI/CD: Variabili protette in GitHub Actions, GitLab CI o pannelli di controllo come Vercel e Netlify.
• Container: Docker Secrets o iniezione diretta tramite docker-compose.yml.

Errori Comuni da Evitare

• Committare il file .env su Git: Se accade, considera tutte le chiavi compromesse e rigenerale immediatamente.
• Usare le stesse API key ovunque: Non usare mai la chiave di produzione per i test locali; rischi di sporcare i dati reali o esaurire il budget.
• Mancata validazione all'avvio: L'app dovrebbe crashare subito se mancano variabili critiche, invece di dare errori criptici a runtime.
• Disseminare `process.env` nel codice: Centralizza l'accesso alle variabili in un unico file di configurazione per facilitare la manutenzione.