s3_to_folder_sync/README.md

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:

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:

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.

[
  {
    "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 devi mappare le cartelle reali del tuo PC/server verso i percorsi usati in local_dir.

Esempio Windows:

volumes:
  - D:/Backup/Foto:/sync/foto
  - D:/Backup/Documenti:/sync/documenti

7) Avvio

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.