Variabili d’ambiente e segreti

Le variabili d’ambiente mantengono la configurazione dell’applicazione separata dal codice sorgente. Ti permettono di eseguire lo stesso codice con impostazioni diverse in sviluppo, staging e produzione. Con Deplomo PaaS , puoi definire i valori a livello di progetto, ambiente, add-on o servizio.

Che cos’è un file env?

Durante lo sviluppo locale, un file .env è un modo comune per salvare le impostazioni come coppie chiave-valore. Una libreria come dotenv può caricarle nell’ambiente del processo locale. Non inserire in Git i file con credenziali reali: aggiungi .env a .gitignore e condividi un .env.example con soli valori segnaposto.

Su Deplomo, aggiungi le variabili dal pannello o dalla CLI. La piattaforma le fornisce al processo del servizio: non devi creare un file .env sul server.

Scegli dove definire una variabile

Usa i segreti di progetto per i valori condivisi tra i servizi, le variabili d’ambiente per quelli diversi da un ambiente all’altro, i collegamenti agli add-on per i valori di connessione generati e le variabili del servizio per i valori specifici di un singolo servizio.

Se più valori runtime hanno lo stesso nome, l’ordine di priorità dal più basso al più alto è:

Project secret > Environment variable > Add-on binding > Service env > Service variable

Le variabili tipizzate del servizio possono quindi sostituire un valore nella sua semplice mappa env. Anche alcuni valori riservati gestiti dalla piattaforma possono avere la precedenza. La build segue una regola distinta: il builder riceve solo le variabili d’ambiente e le variabili tipizzate del servizio abilitate per la build. I segreti di progetto, le credenziali degli add-on e i valori della semplice mappa env del servizio sono disponibili solo a runtime.

Variabili di build e runtime

Tipo	Quando è disponibile	Uso tipico	Da ricordare
Build-time	Durante la creazione dell’immagine o la compilazione degli asset frontend	Accesso a pacchetti privati durante la build; impostazioni pubbliche frontend come `NEXT_PUBLIC_*`	I valori compilati negli asset del browser sono visibili agli utenti. Non passarci segreti.
Runtime	Quando viene eseguito il processo del servizio distribuito	Stringhe di connessione al database e credenziali lato server	Mantieni i segreti lato server a runtime, così non vengono incorporati nell’immagine o negli asset frontend.

Quando cambi un’impostazione runtime, il servizio viene ricreato per applicare il nuovo valore. Se cambi una variabile di build, viene eseguita anche una nuova build per inserirla nell’artefatto.

Non inserire segreti in Git, nei Dockerfile, nelle variabili pubbliche di build, negli screenshot o nei log. Se un segreto viene esposto, sostituiscilo presso il servizio che lo ha emesso e aggiorna la variabile. L’opzione Secret maschera il valore nel pannello; l’output della CLI può mostrarlo, quindi non condividerlo e non salvarlo nei log.

Variabili di riferimento

I riferimenti usano un’altra variabile senza copiarne il valore. Vengono risolti durante il deploy:


# Legge una variabile da un altro servizio del progetto, chiamato db
DATABASE_URL=${{ db.DATABASE_URL }}
 
# Legge un segreto di progetto
APP_KEY=${{ shared.APP_KEY }}
 
# Legge il dominio pubblico generato per un servizio chiamato api
PUBLIC_URL=https://${{ api.DEPLOMO_PUBLIC_DOMAIN }}

${{ shared.KEY }} legge un segreto di progetto, ${{ ServiceName.KEY }} legge una variabile da un altro servizio dello stesso progetto e ${{ KEY }} legge una variabile del servizio corrente. Un riferimento non risolto diventa un valore vuoto. Controlla il nome del servizio e della chiave e verifica che il valore esista nello stesso progetto.

Aggiungi o modifica una variabile dal pannello

Apri le variabili del servizio

Nel pannello, apri il servizio e vai alla sezione Variabili d’ambiente. Per i valori condivisi, apri invece le impostazioni degli ambienti del progetto.

Inserisci chiave e valore

Aggiungi il nome e il valore della variabile. Scegli se renderla disponibile a runtime o durante la build. Usa l’opzione Secret per credenziali e altri valori da mascherare nel pannello.

Salva e controlla l’operazione del servizio

Salva la variabile. Il servizio viene ricreato per applicare le modifiche runtime; le modifiche alle variabili di build richiedono anche una nuova build. Se il servizio non si avvia, controlla l’operazione e i log runtime o di build.

Gestisci le variabili con la CLI

La CLI offre una semplice mappa runtime env e un archivio tipizzato vars. L’archivio tipizzato supporta le opzioni --secret e --build-time.


# Elenca i valori env semplici del servizio
deplomo service env my-app
 
# Imposta o rimuove un valore runtime semplice
deplomo service env my-app set PORT=3000
deplomo service env my-app rm PORT
 
# Elenca le variabili tipizzate con i relativi indicatori build/secret
deplomo service vars my-app
 
# Imposta un segreto runtime mascherato o una variabile frontend di build
deplomo service vars --secret my-app set API_SECRET="replace-with-a-secret"
deplomo service vars --build-time my-app set NEXT_PUBLIC_API_URL="https://api.example.com"

Il comando semplice service env può mostrare i valori elencati. I segreti tipizzati sono mascherati, ma gli altri valori tipizzati possono essere visibili. Non condividere l’output del terminale e non salvarlo nei log.

Proteggi i valori segreti

Contrassegna credenziali e token come segreti nell’archivio tipizzato.
Cambia le credenziali presso il servizio che le ha emesse, aggiorna la variabile e verifica che il servizio abbia applicato il nuovo valore.
Evita di stampare l’intero ambiente del processo, per esempio con console.log(process.env) in Node.js.
Tieni i file .env con valori reali fuori dal repository e dalla relativa cronologia. Se hai inserito una credenziale in un commit, considerala esposta e cambiala.