++ update project
This commit is contained in:
175
README.md
Normal file
175
README.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user