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