Variabili d'ambiente del core

Un deploy ha un solo .env, e la separazione sta nella documentazione: qui ci sono le variabili del core, quelle che valgono per ogni repo cliente e arrivano con la versione del core. Il .env.example del repo cliente elenca le istanze di connettore, la configurazione delle sue pipeline e le poche variabili del core obbligatorie per partire, e rimanda a questa pagina per il resto.

etl env check verifica l'ambiente sull'intero catalogo: elenca le variabili obbligatorie che mancano, ciascuna con chi la dichiara (core, una pipeline o un'istanza di connettore), e avvisa delle chiavi del .env che nessuno dichiara. Legge l'ambiente del processo, e la CLI carica da sola il .env alla radice del repo prima di ogni comando: pnpm etl env check vede lo stesso ambiente di etl serve. Una variabile già nel processo vince su quella del .env. Con un bump del core vede anche le variabili che il core ha aggiunto, che il .env.example del repo cliente non elenca ancora.

Le variabili

Le obbligatorie sono tre, quelle senza cui etl serve non parte: l'API di Noeva, la sua chiave e il workspace. Le altre hanno un default, oppure valgono solo se impostate.

Variabile	Default	A cosa serve
NOEVA_API_BASE_URL	obbligatoria	L'indirizzo di noeva-server-api: worker, stato di pipeline e connettore Noeva passano da lì. etl serve lo dà all'app desktop in GET /deploy, senza credenziali: non scriverle nell'URL.
NOEVA_API_KEY	obbligatoria, segreta	La API key service-role del workspace. Non esce mai da GET /deploy, dai log o dal piano.
NOEVA_WORKSPACE_ID	obbligatoria senza la lista	Il workspace di cui il worker rivendica i processi.
NOEVA_WORKSPACE_IDS	—	Più workspace dello stesso cliente con un'istanza sola, separati da virgole: un poller per workspace, con la stessa NOEVA_API_KEY. Se c'è, prevale su NOEVA_WORKSPACE_ID.
ETL_PIPELINE_WORKSPACES	—	Quali pipeline del catalogo vede ed esegue ogni workspace: <pipeline>:<ws>[|<ws>…], voci separate da virgole. Senza, tutte le pipeline in ogni workspace. Una voce sbagliata blocca l'avvio.
ETL_ENV	dev	L'ambiente di esecuzione: dev, staging o prod.
ETL_LOG_LEVEL	info	Il livello di log: debug, info, warn o error.
ETL_RELEASE	—	La release che esegue la run, scritta nel report. Senza, il commit del repo dell'etl.config.ts (git:<sha>, con -dirty se ci sono modifiche); l'immagine Docker la porta già.
ETL_WORKER_TYPE	etl	Il worker_type dei processi che il worker rivendica.
ETL_POLL_INTERVAL_MS	60000	Ogni quanti millisecondi il worker cerca un processo nuovo.
ETL_HTTP_PORT	3005	La porta di etl serve. Sotto PM2 il default è 9010, messo da ecosystem() solo se il .env non la definisce.
ETL_HTTP_CORS_ORIGIN	*	L'origine ammessa da CORS, una sola: *, oppure quella dell'app desktop (http://tauri.localhost su Windows, tauri://localhost su macOS e Linux).
ETL_RUNS_DIR	.runs	La cartella dello storico locale delle run e delle tracce. Vuota disattiva lo storico, per esempio in un container read-only.
ETL_RUNS_KEEP	200	Quante run conservare nello storico: le più vecchie si cancellano a ogni scrittura.
ETL_TRACES_KEEP	20	Quante tracce conservare. Sono poche perché una traccia porta i valori dei record in chiaro.
ETL_STATE_DIR	.state	La cartella dello stato di pipeline di etl run senza --workspace. Va tenuta diversa da ETL_RUNS_DIR, e in un container su un volume.
ETL_STATE_ACTOR	—	L'autore dichiarato di etl state reset quando manca --actor. Senza, l'utente del sistema operativo.

Le istanze di connettore

Le variabili di un connettore non sono del core: le dichiara il connettore, istanza per istanza, e le elenca il .env.example del repo cliente. Lo schema dei nomi è lo stesso per tutti:

• <TIPO>_INSTANCES elenca le istanze, per esempio PG_INSTANCES=gestionale,dwh;
• le variabili di un'istanza hanno il prefisso <TIPO>_<ID>_: PG_DWH_HOST, PG_DWH_PASSWORD;
• senza <TIPO>_INSTANCES, le variabili senza id (PGHOST, MSSQL_HOST) valgono come l'istanza default.

Le variabili di ogni connettore, con le obbligatorie e le alternative, sono nella sua scheda: vedi i connettori. Quelle di una pipeline le dichiara il suo environment(env), e le elenca la sua scheda.

Vedi anche

• Il server etl serve e il worker, che leggono le variabili di NOEVA_*, ETL_WORKER_TYPE, ETL_POLL_INTERVAL_MS ed ETL_HTTP_*.
• Lo storico delle run e la traccia di una run.
• Lo stato di pipeline.