diff --git a/README.md b/README.md
new file mode 100644
index 0000000..12b3bc9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,221 @@
+# Garage Object Storage + WebUI (Docker Compose)
+
+Setup completo per eseguire **Garage v2** con **Garage WebUI** in Docker, con persistenza su cartella locale/NAS SMB e bootstrap automatico del layout cluster.
+
+## Architettura
+
+Servizi esposti:
+
+- `garage` (dxflrs/garage)
+  - S3 API: `3900`
+  - RPC: `3901`
+  - S3 Web: `3902`
+  - Admin API: `3903`
+- `garage-webui` (khairul169/garage-webui)
+  - UI/API: `3909`
+
+## Struttura progetto
+
+```text
+GARAGE/
+├── .env
+├── docker-compose.yml
+├── garage/
+│   ├── garage.toml
+│   └── meta/
+├── nas_qwince/                  # cartella dati (bind mount, es. SMB/NAS)
+├── bootstrap-garage-layout.sh   # bootstrap layout/ring
+├── start-garage.sh              # avvio stack + bootstrap layout
+├── setup-garage-bucket.sh       # crea bucket + key + permessi
+└── .vscode/tasks.json           # task VS Code opzionale
+```
+
+## Prerequisiti
+
+- Docker + Docker Compose plugin (`docker compose`)
+- Linux host
+- Permessi di scrittura su cartelle bind mount
+
+## Configurazione (`.env`)
+
+Variabili principali:
+
+- `RESTART` = policy restart container (es. `always`)
+- `GARAGE_CONTAINER_NAME` = nome base container (`garage`)
+- `GARAGE_CORE_IMAGE_VERSION` = versione Garage (es. `v2.0.0`)
+- `GARAGE_WEB_IMAGE_VERSION` = tag WebUI (es. `latest`)
+- `GARAGE_WEB_UI_PORT` = porta host WebUI (es. `3909`)
+- `GARAGE_DATA_PATH` = **path relativo al progetto** per i dati (es. `nas_qwince`)
+- `GARAGE_CONFIG_PATH` = cartella config (deve puntare a `garage`)
+- `GARAGE_ADMIN_TOKEN` = token admin usato dalla WebUI
+
+### Importante su percorsi relativi
+
+In `docker-compose.yml` i mount usano `./${...}`: i valori in `.env` devono essere relativi alla cartella del compose.
+
+Esempio corretto:
+
+- `GARAGE_DATA_PATH=nas_qwince`
+- `GARAGE_CONFIG_PATH=garage`
+
+Esempio errato:
+
+- `GARAGE_DATA_PATH=/nas_qwince` (path assoluto root host)
+- `GARAGE_CONFIG_PATH=GARAGE` (case-sensitive: su Linux `garage` ≠ `GARAGE`)
+
+## Avvio rapido
+
+### 1) Avvio stack + bootstrap layout (consigliato)
+
+```bash
+./start-garage.sh
+```
+
+Questo comando fa:
+
+1. `docker compose up -d`
+2. `./bootstrap-garage-layout.sh`
+
+### 2) Avvio manuale
+
+```bash
+docker compose up -d
+./bootstrap-garage-layout.sh
+```
+
+## Script operativi
+
+## `bootstrap-garage-layout.sh`
+
+Controlla lo stato cluster e applica layout single-node se necessario.
+
+- se `layout version = 0` o nodo `NO ROLE ASSIGNED`, applica `layout assign/apply`
+- rileva automaticamente capacità da `GARAGE_DATA_PATH` in GB
+- fallback capacità: `100G` se non rilevabile
+
+Opzioni:
+
+```bash
+./bootstrap-garage-layout.sh --help
+./bootstrap-garage-layout.sh --force-capacity-update
+```
+
+`--force-capacity-update` riallinea la capacità del nodo al valore auto-rilevato anche se il layout è già pronto.
+
+Variabili opzionali:
+
+- `GARAGE_LAYOUT_ZONE` (default `dc1`)
+- `GARAGE_LAYOUT_CAPACITY` (override manuale, es. `80G`)
+
+## `setup-garage-bucket.sh`
+
+Wizard per:
+
+- creare bucket
+- creare access key
+- assegnare permessi R/W/Owner al bucket
+- stampare export env (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, endpoint)
+
+Uso:
+
+```bash
+./setup-garage-bucket.sh
+```
+
+## Accesso servizi
+
+- WebUI: `http://<IP_HOST>:${GARAGE_WEB_UI_PORT}` (tipicamente `3909`)
+- S3 endpoint: `http://<IP_HOST>:3900`
+
+## Comandi utili
+
+Stato servizi:
+
+```bash
+docker compose ps
+```
+
+Log Garage:
+
+```bash
+docker compose logs -f garage
+```
+
+Log WebUI:
+
+```bash
+docker compose logs -f webui
+```
+
+Render config compose risolta:
+
+```bash
+docker compose config
+```
+
+## Troubleshooting
+
+## 1) `pull access denied for garage-webui`
+
+Causa: immagine non namespaced.
+
+Soluzione: usare in compose
+
+```yaml
+image: khairul169/garage-webui:${GARAGE_WEB_IMAGE_VERSION}
+```
+
+## 2) `Could not find expected marker file garage-marker`
+
+Causa: cartella dati montata diversa da quella inizializzata.
+
+Soluzioni:
+
+- verificare `GARAGE_DATA_PATH` (relativo corretto)
+- mantenere la stessa cartella dati storica
+- se migri cartella, assicurarti che i marker/dati siano coerenti
+
+## 3) `Ring not yet ready` / `Could not reach quorum ... 503`
+
+Causa: layout non applicato (`NO ROLE ASSIGNED`).
+
+Soluzione:
+
+```bash
+./bootstrap-garage-layout.sh
+```
+
+## 4) WebUI vuota o API 503
+
+Controllare:
+
+- Garage `Up` e non in restart loop
+- token allineato tra `.env` (`GARAGE_ADMIN_TOKEN`) e `garage/garage.toml` (`admin.admin_token`)
+- endpoint admin raggiungibile
+
+## 5) Eseguito con `sudo` e comportamenti strani
+
+Evitare `sudo` se non necessario: può cambiare contesto permessi/utente e creare file root-owned nel progetto.
+
+## Sicurezza (consigli)
+
+- Cambiare `rpc_secret` e `admin_token` prima di esposizione in rete
+- Limitare esposizione porte su LAN/VPN
+- Usare reverse proxy TLS davanti alla WebUI se accesso remoto
+
+## Backup
+
+Minimo da salvare:
+
+- `garage/meta/`
+- `${GARAGE_DATA_PATH}/` (es. `nas_qwince/`)
+- `garage/garage.toml`
+- `.env`
+
+## VS Code Task
+
+Task disponibile:
+
+- `Garage: up + bootstrap`
+
+Esegue lo stesso flusso di `start-garage.sh`.