> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Variabili d'ambiente e segreti

> Salva token, chiavi API e stringhe di connessione come variabili d'ambiente su Square Cloud da dashboard, CLI o API, e leggile nel codice della tua app.

Tieni token dei bot, chiavi API e password dei database fuori dal codice sorgente. Impostali come variabili d'ambiente dell'applicazione, e il tuo codice li legge durante l'esecuzione come qualsiasi altra variabile.

## Impostare le variabili

Le variabili d'ambiente appartengono a una sola applicazione. Sopravvivono a riavvii e commit, ma un nuovo upload crea una nuova applicazione senza di esse, quindi dovrai impostarle di nuovo lì.

<Tabs>
  <Tab title="Dashboard">
    1. Apri la tua applicazione nella [dashboard](https://squarecloud.app/it/dashboard) e vai in **Settings** → **Environment Variables**.
    2. Aggiungi ogni chiave e valore, oppure importa un file `.env` esistente.
    3. Fai clic su **Save**. La dashboard chiede se riavviare l'applicazione: riavviala perché l'app legga i nuovi valori.

    Quando carichi una nuova applicazione dalla dashboard, puoi anche aggiungere le variabili nella schermata di upload, prima del primo avvio.
  </Tab>

  <Tab title="CLI">
    Esegui i comandi dalla cartella del progetto. La CLI agisce sull'applicazione il cui `ID` si trova nel tuo `squarecloud.app`. Per agire su un'altra, passa `--app <app ID>` (per `list`, passa l'ID come argomento).

    ```bash theme={"system"}
    # Aggiunge o aggiorna variabili (le altre restano invariate)
    squarecloud app env set DISCORD_TOKEN=your-token LOG_LEVEL=info

    # Invia ogni riga di un file .env locale
    squarecloud app env set --from-file .env

    # Elenca le variabili attuali
    squarecloud app env list

    # Rimuove una variabile
    squarecloud app env remove LOG_LEVEL

    # Riavvia per applicare le modifiche
    squarecloud app restart
    ```

    `squarecloud app env replace` sostituisce l'intero set con quello che passi, dopo una conferma. Tutti i comandi e i flag sono descritti in [variabili d'ambiente dalla CLI](/it/cli-reference/environment-variables); per installare la CLI e accedere, consulta la [guida rapida della CLI](/it/cli-reference/quickstart).
  </Tab>

  <Tab title="VS Code">
    Nell'[estensione Square Cloud](/it/vscode-extension/features), fai clic destro sulla tua applicazione nella barra laterale e scegli **Variabili d'ambiente** per elencarle, aggiungerle, modificarle o eliminarle. Poi riavvia l'applicazione per applicare le modifiche.
  </Tab>

  <Tab title="API">
    Invia le variabili a [`POST /v2/apps/{app_id}/envs`](/it/api-reference/endpoint/apps/envs/add_n_edit) con una chiave API che abbia lo scope `envs:write`:

    ```bash theme={"system"}
    curl -X POST "https://api.squarecloud.app/v2/apps/YOUR_APP_ID/envs" \
      -H "Authorization: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"envs": {"DISCORD_TOKEN": "your-token"}}'
    ```

    Lo stesso percorso permette anche di [elencare](/it/api-reference/endpoint/apps/envs/get) (`GET`), [sostituire](/it/api-reference/endpoint/apps/envs/overwrite) (`PUT`) e [rimuovere](/it/api-reference/endpoint/apps/envs/remove) (`DELETE`) le variabili. L'API non riavvia l'applicazione: chiama poi l'[endpoint di riavvio](/it/api-reference/endpoint/apps/restart).
  </Tab>
</Tabs>

<Warning>Le variabili vengono caricate all'avvio dell'applicazione. Dopo ogni modifica riavvia l'applicazione, altrimenti continua a funzionare con i vecchi valori.</Warning>

## Leggerle nel codice

<CodeGroup>
  ```javascript Node.js theme={"system"}
  const token = process.env.DISCORD_TOKEN;

  if (!token) {
    throw new Error("DISCORD_TOKEN is not set");
  }
  ```

  ```python Python theme={"system"}
  import os

  token = os.environ.get("DISCORD_TOKEN")

  if not token:
      raise RuntimeError("DISCORD_TOKEN is not set")
  ```
</CodeGroup>

Fermarsi subito quando manca una variabile ti dà un messaggio chiaro nei log, invece di un errore confuso più avanti, come un token non valido.

## Variabili impostate da Square Cloud

La tua applicazione si avvia con queste variabili già definite:

| Variabile | Valore | A cosa serve |
| - | - | - |
| `PORT` | `80` | Scegliere la porta su cui il tuo server web resta in ascolto. |
| `HOST` | `0.0.0.0` | Scegliere l'indirizzo a cui si associa il tuo server web. |
| `SQUARECLOUD_APP_ID` | L'ID della tua applicazione | Identificare l'applicazione durante l'esecuzione. |
| `NODE_ENV` | `production` | Indicare alle librerie Node.js che sono in produzione (runtime Node.js e TypeScript). |

<Warning>Non sovrascrivere `PORT` o `HOST` su un sito: la piattaforma raggiunge solo un server sulla porta 80 e sull'host `0.0.0.0`.</Warning>

Poiché `NODE_ENV` vale `production`, `npm install` salta le `devDependencies`. Se il tuo comando `START` compila il progetto (per esempio con `typescript` o `vite`), elenca quegli strumenti di build sotto `dependencies` in `package.json`.

## Come le variabili arrivano alla tua app

Square Cloud salva le variabili in un file `.squarecloud/.env` dentro l'applicazione e le carica con una shell a ogni avvio, prima dell'installazione delle dipendenze e dell'esecuzione del comando `START` o del file `MAIN`. Due conseguenze:

* I **nomi** dovrebbero usare lettere, cifre e underscore, e non iniziare con una cifra.
* I **valori** con spazi o caratteri della shell come `$`, `&`, `;` o `|` vanno messi tra virgolette, altrimenti la shell li tronca o li espande. La dashboard e `squarecloud app env set` li mettono tra virgolette per te. Nell'estensione per VS Code o nell'API, racchiudi tu stesso un valore del genere tra virgolette singole: digita `'p@ss word$1'`, oppure invia `"PASSWORD": "'p@ss word$1'"` nel body dell'API.

I limiti sono 256 variabili per applicazione, 1.024 caratteri per nome e 4.096 caratteri per valore. I siti statici (HTML/CSS) non supportano le variabili d'ambiente e restituiscono `STATIC_APP_ENV_NOT_SUPPORTED`.

## Tieni i segreti fuori dall'upload

Se il tuo codice carica da sé un file `.env` (per esempio con `dotenv`), quel file deve essere nell'upload. Elencare `.env` in [`squarecloud.ignore`](/it/getting-started/squarecloud-ignore) avvia allora l'app senza i suoi segreti, e un bot fallisce con un token non valido.

La configurazione più sicura: sposta ogni valore del tuo `.env` nelle variabili d'ambiente dell'applicazione, come mostrato sopra. Una volta impostate, puoi escludere `.env` dall'upload e dal tuo repository Git. `dotenv` non sovrascrive le variabili già esistenti, quindi lo stesso codice continua a funzionare sulla tua macchina e su Square Cloud.

<Warning>Non fare mai commit di token o password in un repository pubblico. Se uno viene esposto, revocalo presso il fornitore (per esempio, reimposta il token del bot nel Discord Developer Portal) e imposta qui il nuovo valore.</Warning>

## Prossimi passi

<CardGroup cols={2}>
  <Card title="File di configurazione" icon="gear-complex-code" href="/it/getting-started/config-file">
    Imposta `MAIN`, `MEMORY`, `START` e gli altri campi di `squarecloud.app`.
  </Card>

  <Card title="Ospita un bot Discord" icon="discord" href="/it/tutorials/bots/discord">
    Pubblica un bot che legge il token da una variabile d'ambiente.
  </Card>

  <Card title="Errori dei bot Discord" icon="bug" href="/it/platform/troubleshooting/discord-bot-errors">
    Risolvi token non validi, intent mancanti e bot che vanno offline.
  </Card>

  <Card title="Errori di connessione al database" icon="database" href="/it/platform/troubleshooting/database-connection-errors">
    Connettiti con una `DATABASE_URL` e le impostazioni SSL corrette.
  </Card>
</CardGroup>