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

# Ambiente

> Configurazione del runtime per lo sviluppo locale e i deployment hosted.

# Ambiente

Questa pagina è il riferimento canonico per la configurazione del runtime del repository.

## Configurazione locale

Copia i file di esempio prima di avviare l'area di lavoro:

```bash theme={null}
cp apps/app/.env.example apps/app/.env.local
cp apps/api/.env.example apps/api/.env.local
cp apps/web/.env.example apps/web/.env.local
```

## Variabili Supabase richieste

* `NEXT_PUBLIC_SUPABASE_URL` per qualsiasi runtime che crea un client Supabase
* `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` per client browser e client scoped alla richiesta
* `SUPABASE_SECRET_KEY` per l'accesso admin solo lato server

## Variabili Meta richieste per invii reali e verifica dei webhook

* `WHATSAPP_META_ACCESS_TOKEN` per l'invio in uscita lato worker verso la Meta Graph API
* `WEBHOOK_SIGNATURE_SECRET` per validare `x-hub-signature-256` sui webhook in entrata
* `META_WEBHOOK_VERIFY_TOKEN` se vuoi una verifica deterministica della challenge per l'handshake del webhook Meta

Queste variabili di ambiente restano valide come fallback di bootstrap a livello di piattaforma. Quando un'area di lavoro archivia le proprie credenziali del provider tramite l'app operatore, i valori dell'area di lavoro basati su Vault hanno la precedenza.

## Alias legacy accettati

Il repository accetta ancora questi mentre le integrazioni vengono migrate:

* `NEXT_PUBLIC_SUPABASE_ANON_KEY`
* `SUPABASE_SERVICE_ROLE_KEY`

Il nuovo lavoro dovrebbe usare i nomi publishable e secret key.

## Selettore della modalità dati

* `WHATSAPP_PLATFORM_DATA_MODE=mock` mantiene l'app operatore, le route API e la documentazione in esecuzione sullo store tipizzato in memoria
* `WHATSAPP_PLATFORM_DATA_MODE=supabase` abilita il percorso dati basato su Supabase dove implementato

Se la variabile viene omessa, il repository resta in modalità `mock` di default.

## Variabili opzionali

* `SUPABASE_DB_URL` per gli strumenti Postgres diretti, le migrazioni e i job lato server che necessitano della connection string. È richiesta anche se vuoi che i segreti dei provider gestiti dall'area di lavoro vengano archiviati in Supabase Vault dall'interfaccia del prodotto.
* `WHATSAPP_META_API_VERSION` per sovrascrivere la versione di default della Graph API. Il repository usa `v25.0` come default.
* `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS` come elenco separato da virgole di email autorizzate a effettuare il bootstrap dell'accesso privilegiato all'area di lavoro senza un invito.
* `WORKSPACE_ALLOW_FIRST_CLAIM` per consentire la richiesta del ruolo owner da parte del primo utente quando non esistono ancora membri dell'area di lavoro. Il comportamento di default è disabilitato, a meno che tu non lo imposti esplicitamente su `true`.
* `DEFAULT_WORKSPACE_SLUG` per il bootstrap del contesto dell'area di lavoro predefinita
* `DEFAULT_CHANNEL_WABA_ID`, `DEFAULT_CHANNEL_PHONE_NUMBER_ID`, `DEFAULT_CHANNEL_PHONE_E164` e `DEFAULT_CHANNEL_DISPLAY_NAME` per i metadati del canale predefinito

## Suddivisione del deployment

* `apps/web`, `apps/app` e `apps/api`, ospitati su Vercel, devono ricevere le variabili Supabase pubbliche necessarie per il loro percorso di runtime
* i runtime server come `apps/api`, `apps/worker` e `apps/control-plane` necessitano anche di `SUPABASE_SECRET_KEY`
* `apps/worker` su Railway necessita di `WHATSAPP_META_ACCESS_TOKEN` per l'invio reale al provider
* `apps/api` su Vercel necessita di `WEBHOOK_SIGNATURE_SECRET` per l'ingestione firmata dei webhook nell'attuale postura alpha
* solo i runtime server dovrebbero ricevere `SUPABASE_DB_URL`
* il server dell'app operatore necessita di `SUPABASE_DB_URL` se vuoi che `/setup` e **Impostazioni → Provider** archivino o ruotino i segreti gestiti dall'area di lavoro
* il server dell'app operatore necessita anche di `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS` se vuoi che il percorso del primo operatore privilegiato sia esplicito invece che solo su invito
* se un primo operatore autenticato raggiunge `/pending-access` con zero membri dell'area di lavoro, recupera impostando `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS`, abilitando temporaneamente `WORKSPACE_ALLOW_FIRST_CLAIM=true`, oppure creando manualmente la riga `workspace_members`; non è necessario eliminare l'utente auth
* `apps/control-plane` resta nel repository ma non fa parte dell'attuale contratto alpha hosted, a meno che la decisione sull'ingress non cambi

## Leggi anche

* [Guida rapida](/it/quickstart)
* [Sviluppo](/it/development)
* [Architettura della piattaforma](/it/platform/architecture)