# 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/
├── _DATA-FOLDER_/                  # cartella dati (bind mount, es. SMB/NAS) > DEVE ESSERE GIA' ESISTENTE
├── 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`.