> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Configura l'archiviazione file

Upload con scope workspace su memory o qualsiasi bucket compatibile S3.

## Procedura dettagliata per principianti

Prerequisiti: leggi le due guide per principianti di seguito, completa la configurazione locale del Web e apri questo monorepo alla radice nel tuo editor. Le impostazioni Web appartengono a `apps/web/.env.local`; Next.js non legge la radice `.env`. `/dashboard` nella modalità falsa predefinita è una demo senza database; `/auth` necessita di un database migrato.

Termini rapidi: uno spazio di lavoro è costituito da utenti, dati e impostazioni separati di un team. Il server è il backend affidabile; mantenere le chiavi del provider fuori dal browser e dal codice del telefono. Una migrazione è una modifica del database con versione che crea o aggiorna tabelle. Un modello AI è il motore che risponde; il catalogo dei modelli è l'elenco del server degli ID e dei prezzi dei modelli disponibili. Un fornitore è un servizio esterno come un servizio di intelligenza artificiale, posta elettronica o fatturazione. Un diritto è una concessione che consente a un'area di lavoro di utilizzare una funzionalità. Un webhook è un messaggio che un servizio invia allo URL di un altro servizio.

1. Per una prova senza credenziali, mantenere `STORAGE_PROVIDER=memory`. Se questo pagamento non ha un controllo di caricamento visibile, chiedi al tuo agente di codifica di ispezionare `apps/web/app/api/storage/avatar/route.ts`, `apps/web/app/api/storage/logo/route.ts`, `apps/web/app/api/storage/organization-logo/route.ts` e la pagina delle impostazioni corrispondenti prima di collegare una piccola immagine di esempio.

2. Per verificare la persistenza, impostare `STORAGE_PROVIDER=s3`, `STORAGE_REGION` e `STORAGE_BUCKET` in `apps/web/.env.local`, aggiungere localmente le credenziali di test solo del server e riavviare.

3. L'immagine dovrebbe essere ricaricata dalla memoria. I file di memoria scompaiono al riavvio del processo; per gli errori S3, controlla il bucket, l'endpoint e la policy di accesso.

Per il codice personalizzato, inizia con `prompts/README.md` in dotazione e copia il prompt più vicino: `prompts/new-app-screen.md` per la schermata di un'app o `prompts/new-landing-page.md` per una pagina pubblica. Per il lavoro su server, database o provider, assegna al tuo agente di codifica il compito di questa guida e chiedigli di leggere `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` e i mirror `.ai/` corrispondenti; controllare gli esatti file sorgente nominati qui; elencare file e controlli prima della modifica; preservare la proprietà dello spazio di lavoro e i segreti solo del server; e mostrarti la differenza. Indicagli il comportamento desiderato, i campi di input e output, i ruoli consentiti, i successi e gli errori previsti e l'account, il fornitore o il dispositivo di prova. Utilizzare valori campione; non incollare mai un vero segreto.

[Prima di iniziare](https://supastack.dev/it/docs/web/before-you-start.md)

[Nozioni di base sui terminali](https://supastack.dev/it/docs/web/terminal-basics.md)

[Configurazione locale Web](https://supastack.dev/it/docs/web/ship-in-5-minutes.md)

[Messaggi dell'agente e memoria del progetto](https://supastack.dev/it/docs/web/agents.md)


## Seleziona il backend di archiviazione

`STORAGE_PROVIDER=memory` è l’impostazione predefinita senza credenziali. `local` scrive gli oggetti su disco in `STORAGE_LOCAL_DIR` (`./.data/storage` per impostazione predefinita, richiesto esplicitamente in produzione) e li trasmette tramite URL firmati con HMAC a scadenza su `/api/storage/local/[...key]` (`STORAGE_LOCAL_SIGNING_SECRET`, con fallback su `AUTH_SECRET`) per i deployment su singolo server. `s3` usa `apps/web/src/storage-runtime.ts` per comporre il client AWS SDK sul contratto essenziale `@supastack/storage`, supportando Supabase Storage e MinIO con URL path-style abilitati per impostazione predefinita.

```
STORAGE_PROVIDER=s3
STORAGE_REGION=us-east-1
STORAGE_BUCKET=your-product-bucket
# Set STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY on the server.
# Optional: STORAGE_ENDPOINT, STORAGE_FORCE_PATH_STYLE, STORAGE_PUBLIC_BASE_URL
# Self-hosted single-server disk storage:
# STORAGE_PROVIDER=local
# STORAGE_LOCAL_DIR=./.data/storage
# STORAGE_LOCAL_SIGNING_SECRET=
# Local MinIO Compose overrides: MINIO_ROOT_USER / MINIO_ROOT_PASSWORD
```


## Riutilizzare i limiti di caricamento

I percorsi spediti coprono oggetti, avatar, loghi di profili e loghi di organizzazioni sotto `/api/storage/`. Risolvono le autorizzazioni di identità/area di lavoro e convalidano la forma di caricamento prima dell'archiviazione. Ispeziona la politica di dimensione/tipo del percorso scelto invece di accettare chiavi arbitrarie dell'oggetto client.

Gli URL pubblici sono presentazioni, non autorizzazioni. Mantieni i contenuti protetti entro il limite di lettura verificato dell'applicazione e configura la policy bucket/CDN per i dati del tuo prodotto.


## Testare il comportamento di archiviazione reale

Testare caricamenti consentiti/negati, MIME e rifiuto delle dimensioni, percorsi di aree di lavoro esterne, oggetti mancanti e errori del provider. La modalità memoria non persiste tra i processi; verificare l'archiviazione e il recupero rispetto al backend selezionato prima del rilascio.

[Configurazione archiviazione Supabase](https://supastack.dev/it/docs/web/project-structure.md)

[Carica inventario percorsi](https://supastack.dev/it/docs/web/project-structure.md)


## Installazione e configurazione

1. STORAGE_PROVIDER=memory (il default) mantiene gli upload in-process — giusto per sviluppo e test.

2. Per file reali, imposta STORAGE_PROVIDER=s3 con un bucket e una coppia di chiavi di accesso. STORAGE_ENDPOINT seleziona qualsiasi servizio compatibile S3 — Supabase Storage su https://<ref>.supabase.co/storage/v1/s3, MinIO o AWS stesso.

3. STORAGE_FORCE_PATH_STYLE passa a true di default appena è impostato un endpoint — Supabase e MinIO lo richiedono. Impostalo a false solo per un endpoint custom virtual-hosted.

4. Opzionalmente punta STORAGE_PUBLIC_BASE_URL a una CDN così gli URL pubblici degli oggetti si risolvono lì.

```
STORAGE_PROVIDER=s3
STORAGE_ENDPOINT=https://<ref>.supabase.co/storage/v1/s3
STORAGE_REGION=us-east-1            # Supabase: project region
STORAGE_BUCKET=<bucket>
STORAGE_ACCESS_KEY_ID=…
STORAGE_SECRET_ACCESS_KEY=…
STORAGE_PUBLIC_BASE_URL=https://cdn.example.com   # optional

# No bucket yet? Local S3-compatible storage ships in compose:
docker compose --profile storage up -d minio    # console on :9001
```


## Flusso di implementazione

Upload e letture passano per route autenticate che risolvono prima il workspace — /api/storage/objects più le route dedicate per avatar e logo. Ogni chiave archiviata è namespacata come {workspaceId}/{purpose}/{safeName} tramite buildWorkspaceObjectKey.

Le credenziali restano solo server; il browser non vede mai bucket né chiavi.

Gli upload funzionano? Continua con Configura l'osservabilità.


## Verifica e risoluzione dei problemi

Verifica che un upload faccia il round-trip, che un secondo workspace non possa leggere l'oggetto e che dimensioni eccessive o content type non consentiti falliscano. Errori di firma o 403 contro Supabase o MinIO di solito significano che STORAGE_FORCE_PATH_STYLE è sbagliato per l'endpoint.


Per continuare la configurazione, leggi [Configura l'osservabilità](https://supastack.dev/it/docs/web/setup-observability.md).


## Successivo

[Modulo storage](https://supastack.dev/it/docs/modules/storage.md)