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

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)

./start-garage.sh

Questo comando fa:

docker compose up -d
./bootstrap-garage-layout.sh

2) Avvio manuale

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:

./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:

./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:

docker compose ps

Log Garage:

docker compose logs -f garage

Log WebUI:

docker compose logs -f webui

Render config compose risolta:

docker compose config

Troubleshooting

1) `pull access denied for garage-webui`

Causa: immagine non namespaced.

Soluzione: usare in compose

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:

./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.

README.md

Garage Object Storage + WebUI (Docker Compose)