176 lines
4.6 KiB
Markdown
176 lines
4.6 KiB
Markdown
# Mirror S3 su Cartelle Locali
|
|
|
|
Servizio Docker che copia (in mirroring) uno o piu bucket S3 dentro cartelle locali gia esistenti, con:
|
|
|
|
- pianificazione automatica (cron, timezone UTC),
|
|
- dashboard web con stato e log in tempo reale,
|
|
- avvio manuale delle sync dalla UI,
|
|
- notifiche Gotify all'inizio e alla fine di ogni sync.
|
|
|
|
## A cosa serve
|
|
|
|
Esempio pratico:
|
|
|
|
- hai 2 bucket S3,
|
|
- hai 2 cartelle sul PC o server,
|
|
- vuoi che le cartelle siano sempre allineate ai bucket,
|
|
- vuoi vedere stato, errori e storico da una pagina web.
|
|
|
|
## 1) Configura il file .env (guida semplice)
|
|
|
|
Copia `.env.example` in `.env` e modifica i valori.
|
|
|
|
Variabili principali:
|
|
|
|
- `WEB_PORT`: porta della dashboard web.
|
|
- `JOB_COUNT` + blocchi `JOB_1_*`, `JOB_2_*`, ecc.: elenco job in formato semplice.
|
|
- `AWS_ACCESS_KEY_ID` e `AWS_SECRET_ACCESS_KEY`: credenziali S3.
|
|
- `S3_ENDPOINT_URL`: opzionale, utile per storage compatibili S3 (MinIO, Wasabi, ecc.).
|
|
- `GOTIFY_URL` e `GOTIFY_TOKEN`: opzionali, per ricevere notifiche push.
|
|
|
|
Esempio completo di `.env` semplice per 2 bucket:
|
|
|
|
```env
|
|
WEB_PORT=8080
|
|
|
|
AWS_ACCESS_KEY_ID=LA_TUA_ACCESS_KEY
|
|
AWS_SECRET_ACCESS_KEY=LA_TUA_SECRET_KEY
|
|
AWS_REGION=eu-west-1
|
|
S3_ENDPOINT_URL=
|
|
|
|
RUN_ON_STARTUP=true
|
|
MIRROR_DELETE_LOCAL_EXTRAS=true
|
|
DEFAULT_SCHEDULE_CRON=*/30 * * * *
|
|
|
|
GOTIFY_URL=http://192.168.1.50:8088
|
|
GOTIFY_TOKEN=IL_TUO_TOKEN_GOTIFY
|
|
GOTIFY_PRIORITY_START=5
|
|
GOTIFY_PRIORITY_END=5
|
|
|
|
JOB_COUNT=2
|
|
|
|
JOB_1_NAME=foto
|
|
JOB_1_BUCKET=bucket-foto
|
|
JOB_1_LOCAL_DIR=/sync/foto
|
|
JOB_1_PREFIX=
|
|
JOB_1_SCHEDULE=*/15 * * * *
|
|
JOB_1_DELETE_LOCAL_EXTRAS=true
|
|
|
|
JOB_2_NAME=documenti
|
|
JOB_2_BUCKET=bucket-documenti
|
|
JOB_2_LOCAL_DIR=/sync/documenti
|
|
JOB_2_PREFIX=archivio/
|
|
JOB_2_SCHEDULE=0 * * * *
|
|
JOB_2_DELETE_LOCAL_EXTRAS=true
|
|
```
|
|
|
|
## 2) Come aggiungere un terzo job (facile)
|
|
|
|
Se vuoi aggiungere un altro bucket:
|
|
|
|
- cambia `JOB_COUNT=3`
|
|
- aggiungi le righe `JOB_3_*`
|
|
|
|
Esempio:
|
|
|
|
```env
|
|
JOB_3_NAME=video
|
|
JOB_3_BUCKET=bucket-video
|
|
JOB_3_LOCAL_DIR=/sync/video
|
|
JOB_3_PREFIX=
|
|
JOB_3_SCHEDULE=0 2 * * *
|
|
JOB_3_DELETE_LOCAL_EXTRAS=true
|
|
```
|
|
|
|
## 3) Significato campi JOB_n_*
|
|
|
|
- `JOB_n_NAME`: nome visualizzato in dashboard.
|
|
- `JOB_n_BUCKET`: nome bucket sorgente.
|
|
- `JOB_n_LOCAL_DIR`: cartella di destinazione nel container.
|
|
- `JOB_n_PREFIX`: opzionale, limita la sync a una sottocartella del bucket.
|
|
- `JOB_n_SCHEDULE`: frequenza con sintassi cron a 5 campi.
|
|
- `JOB_n_DELETE_LOCAL_EXTRAS`: se `true`, cancella in locale file non piu presenti su S3.
|
|
- `JOB_n_REGION`: opzionale, se vuoi forzare una regione diversa da AWS_REGION.
|
|
- `JOB_n_ENDPOINT_URL`: opzionale, endpoint S3 custom per quel job.
|
|
|
|
## 4) Esempio sintassi JSON (opzionale avanzato)
|
|
|
|
Se preferisci, puoi ancora usare il vecchio formato JSON con `SYNC_JOBS_JSON`.
|
|
La modalita semplice con `JOB_COUNT` resta consigliata per utenti non tecnici.
|
|
|
|
Ogni oggetto dell'array rappresenta un job.
|
|
|
|
```json
|
|
[
|
|
{
|
|
"name": "foto",
|
|
"bucket": "bucket-foto",
|
|
"local_dir": "/sync/foto",
|
|
"endpoint_url": "",
|
|
"prefix": "",
|
|
"schedule": "*/15 * * * *",
|
|
"delete_local_extras": true
|
|
}
|
|
]
|
|
```
|
|
|
|
Significato campi:
|
|
|
|
- `name`: nome visualizzato in dashboard.
|
|
- `bucket`: nome bucket sorgente.
|
|
- `local_dir`: cartella di destinazione nel container.
|
|
- `endpoint_url`: lascia vuoto per AWS; compila per S3 compatibile.
|
|
- `prefix`: opzionale, limita la sync a una sottocartella del bucket.
|
|
- `schedule`: frequenza con sintassi cron a 5 campi.
|
|
- `delete_local_extras`: se `true`, cancella in locale file non piu presenti su S3.
|
|
|
|
## 5) Esempi semplici di pianificazione cron
|
|
|
|
Formato: `minuto ora giorno mese giorno_settimana`
|
|
|
|
Esempi utili:
|
|
|
|
- `*/15 * * * *` ogni 15 minuti
|
|
- `0 * * * *` a ogni ora (minuto 0)
|
|
- `0 2 * * *` ogni notte alle 02:00
|
|
- `0 8 * * 1` ogni lunedi alle 08:00
|
|
|
|
## 6) Collega le cartelle locali in docker-compose
|
|
|
|
In [docker-compose.yml](docker-compose.yml) devi mappare le cartelle reali del tuo PC/server verso i percorsi usati in `local_dir`.
|
|
|
|
Esempio Windows:
|
|
|
|
```yaml
|
|
volumes:
|
|
- D:/Backup/Foto:/sync/foto
|
|
- D:/Backup/Documenti:/sync/documenti
|
|
```
|
|
|
|
## 7) Avvio
|
|
|
|
```bash
|
|
docker compose up --build -d
|
|
```
|
|
|
|
Dashboard:
|
|
|
|
- `http://localhost:8080` (oppure la porta impostata in `WEB_PORT`)
|
|
|
|
## Comportamento del mirror
|
|
|
|
- Direzione: **S3 -> cartella locale**.
|
|
- Scarica file nuovi o modificati.
|
|
- Se `delete_local_extras=true`, elimina file locali non presenti nel bucket.
|
|
- Invia notifica Gotify a inizio e fine sync (anche in caso di errore).
|
|
|
|
## API disponibili
|
|
|
|
- `GET /api/status` stato completo e log.
|
|
- `POST /api/run/<job_name>` avvio manuale di un job.
|
|
- `POST /api/run-all` avvio manuale di tutti i job.
|
|
|
|
## Nota sicurezza
|
|
|
|
Non salvare credenziali reali su repository Git pubblici. Il file `.env` e gia ignorato da Git.
|