222 lines
4.9 KiB
Markdown
222 lines
4.9 KiB
Markdown
# 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`.
|