fidelius-cli

Mette le variabili di un Fidelius Environment nell'ambiente di un processo, senza librerie e senza lasciare credenziali nel repository.

fidelius-cli config-env composer1          # una volta sola: incolli la chiave
fidelius-cli run composer1 -- python app.py

Dentro app.py funziona os.environ["MONGODB_URI"]. Nessun import, nessun .env, nessun segreto committato.

Installazione

npm install -g fidelius-cli

Oppure il pacchetto Debian (nessun runtime richiesto, è un binario statico):

sudo apt install ./fidelius-cli_0.1.0_amd64.deb

Configurare un environment

L'alias è un nome tuo, locale a questa macchina: serve a te per ricordarti quale environment è, non deve coincidere con niente su Fidelius.

$ fidelius-cli config-env composer1
Environment Fidelius → alias "composer1"
URL del backend Fidelius (es. https://fidelius-ws.esempio.dev): https://fidelius-ws.gottigiorgio.dev
API-Key o URI di accesso: ●●●●●●●●●●●●●●●●●●●●●●●●
✓ composer1 configurato → «app-backend» (javascript, 7 variabili)
  store: /home/tu/.fidelius/config.json

La chiave la generi dalla UI Fidelius, nella scheda dell'environment → Chiavi di accesso. Vanno bene sia una API-Key (env_xxxxx_yyyyy) sia un URI di accesso (envmgr://...@access). L'URL del backend lo chiede solo la prima volta.

Da quel momento:

fidelius-cli check composer1       # verifica la chiave, mostra i NOMI delle variabili
fidelius-cli list-env              # cosa hai configurato
fidelius-cli forget-env composer1  # cancella l'alias da questa macchina

Lanciare qualcosa

run carica l'environment e poi diventa il comando che gli passi (exec): non resta un processo intermedio, i segnali arrivano direttamente all'applicazione e il suo exit code è quello che vedi tu.

fidelius-cli run composer1 -- python app.py
fidelius-cli run composer1 -- node server.js
fidelius-cli run composer1 -- npm run dev
fidelius-cli run composer1 -- bash          # una shell con l'ambiente già dentro

Se preferisci restare nella shell corrente, inject-env stampa gli export da valutare:

eval "$(fidelius-cli inject-env composer1)"

E se vuoi usare le librerie fidelius-env invece delle variabili già pronte, inject-api-key inietta solo la chiave e l'URL del backend:

eval "$(fidelius-cli inject-api-key composer1)"
node -e 'require("fidelius-env").loadEnv(process.env.FIDELIUS_API_KEY)'

Docker Compose

setup-composer aggancia un servizio a un environment e ti dice quali variabili puoi togliere dal file:

$ fidelius-cli setup-composer docker-compose.yml composer1 --service backend

  NODE_ENV               ×  non presente su Fidelius - la lascio nel compose
  MONGODB_URI            ✓  presente su Fidelius, valore identico
  JWT_SECRET             ✓  presente su Fidelius, valore identico
  ALLOWED_ORIGIN         ✓  presente su Fidelius, valore identico

  3 variabili del compose sono già su Fidelius: aggiungi --strip-env per toglierle dal file.

Con --strip-env il risultato è questo:

   backend:
     image: node:22-alpine
     volumes:
       - ./backend:/backend
+      - ${HOME}/.fidelius:/etc/fidelius:ro  # fidelius-cli
+      - ${HOME}/.local/bin/fidelius-cli:/usr/local/bin/fidelius-cli:ro  # fidelius-cli
+    # fidelius-cli:command-was sh -c "npm install && npm start"
+    command: fidelius-cli run composer1 -- sh -c "npm install && npm start"
     environment:
       NODE_ENV: production
-      MONGODB_URI: mongodb://root:tteT51iDmS5Cz4gC@mongodb:27017/fidelius
-      JWT_SECRET: 4E7_Zoaf-MhbMOIbqtTTAoQ6CFJDhxNsJ0Jrx_uiBAgkY6rTpO50Lq0fnXrqfTtK

Nel repository non resta nessun segreto: solo due path e il nome di un alias. Le credenziali vivono in ~/.fidelius/ sulla macchina, che sia il tuo portatile o il server di produzione, e ci arrivano nel container attraverso il mount.

Il comando non riscrive il file: applica modifiche riga per riga, quindi commenti, indentazione e virgolette restano esattamente com'erano. --dry-run mostra il diff senza toccare niente, --yes salta la conferma, e si torna indietro con:

fidelius-cli setup-composer docker-compose.yml --remove

(le variabili rimosse con --strip-env non tornano: ormai vivono su Fidelius.)

Se il binario non può essere montato

Il mount funziona quando l'host è Linux, perché è lo stesso binario a girare dentro il container. Su macOS o Windows non è possibile: installa la CLI dentro l'immagine e aggiungi --no-binary-mount.

RUN npm install -g fidelius-cli

Dove cerca la chiave

In ordine:

1. --key / --uri passati sulla riga di comando
2. l'alias nello store locale (~/.fidelius/config.json)
3. le variabili d'ambiente FIDELIUS_API_KEY o FIDELIUS_ACCESS_URI

L'ultimo punto è il fallback per i container in cui non si vuole montare niente: basta una sola variabile nell'ambiente al posto di tutte quelle che conteneva prima.

Lo store si cerca in $FIDELIUS_CONFIG_DIR, poi ~/.fidelius, poi /etc/fidelius (dove setup-composer lo monta). fidelius-cli status dice sempre cosa verrebbe usato qui e ora.

I segreti non finiscono a schermo

inject-env, print-env e check --show-environment-secrets si rifiutano di stampare valori se lo standard output è un terminale: nove volte su dieci vuol dire che l'eval o la redirezione sono stati dimenticati.

$ fidelius-cli inject-env composer1
fidelius-cli: mi rifiuto di stampare segreti su un terminale.
  Questo comando va valutato dalla shell:

    eval "$(fidelius-cli inject-env composer1)"

  Se vuoi davvero vederli a schermo: --show-environment-secrets

Il flag è volutamente lungo da scrivere. check senza flag mostra i nomi delle variabili ma mai i valori, e basta quasi sempre.

Lo store viene scritto con permessi 600 in una directory 700, in modo atomico (file temporaneo più rename), così un'interruzione non può troncarlo.

Comandi

| Comando | | | --- | --- | | config-env <alias> | memorizza la chiave di un environment | | list-env | elenca gli alias configurati | | forget-env <alias> | cancella un alias da questa macchina | | rename-env <alias> <nuovo> | rinomina un alias | | set-url <url> | backend Fidelius predefinito | | run <alias> -- <comando> | lancia un comando con le variabili dentro | | inject-env <alias> | export da valutare con eval | | inject-api-key <alias> | solo FIDELIUS_API_KEY e FIDELIUS_API_URL | | check <alias> | verifica la chiave, elenca i nomi delle variabili | | print-env <alias> | --format dotenv\|json\|shell | | status | store, backend, cosa verrebbe risolto qui | | setup-composer <file> <alias> | aggancia un compose file |

run, inject-env e print-env accettano --only, --except e --prefix per filtrare o rinominare le variabili.

Exit code

Servono negli script e nelle catene &&, dove "è fallito" da solo non dice se ha senso ritentare.

| | | | --- | --- | | 0 | tutto bene | | 1 | errore d'uso | | 2 | alias non configurato, o manca l'URL del backend | | 3 | chiave non valida o revocata | | 4 | backend irraggiungibile | | 5 | contenuto dell'environment non leggibile | | 126 / 127 | il comando di run non è eseguibile / non esiste |

Cosa sa leggere

Il contenuto di un environment Fidelius è codice vero (un modulo CommonJS o uno script Python) e le librerie fidelius-env lo eseguono. Un binario statico non ha un runtime a disposizione, quindi lo legge: accetta assegnamenti di valori letterali - stringhe, numeri, booleani - che è di ciò che un file di configurazione è fatto.

module.exports = {
  MONGODB_URI: "mongodb://...",   // ✓
  PORT: 5858,                      // ✓
  DEBUG: false,                    // ✓
  BASE: `${host}/v1`,              // ✗ calcolata a runtime
  KEY: process.env.HOME,           // ✗ idem
}

Su un valore che non sa leggere non tira a indovinare: si ferma, nomina la riga e la variabile, e ti dice di usare la libreria se il valore dev'essere davvero calcolato a runtime. Numeri e booleani vengono convertiti in stringa con le stesse regole del linguaggio d'origine (false in JavaScript, False in Python), così il valore che arriva nel processo è identico a quello che ci avrebbe messo la libreria.

Sviluppo

Go non serve installato: si compila in un container.

make build      # binario in dist/
make check      # fmt, vet, test
make dist       # linux e darwin, amd64 e arm64
make packages   # pacchetti npm e .deb in dist/packages/