Una soluzione semplice per sincronizzare automaticamente file da Amazon S3 (o servizi compatibili) direttamente sul tuo computer, con una dashboard web intuitiva.

Non hai bisogno di saper programmmare - basta configurare un file e avviare!

🎯 Cos'è?

Immagina di avere una cartella su Amazon S3 (il cloud storage di Amazon) con file importanti. Questo progetto fa una cosa semplice:

Copia automaticamente i file da S3 alla tua cartella locale, e ti mostra in tempo reale cosa sta succedendo.

Esempi di utilizzo:

✅ Backup automatico di documenti
✅ Sincronizzazione di foto da una cartella cloud
✅ Mirror di dati aziendali
✅ Gestione di più bucket S3 simultaneamente

📋 Requisiti

Hai bisogno di:

Docker installato sul tuo computer
- Scarica Docker da qui
- È un programma che permette di eseguire applicazioni in modo isolato
Credenziali S3
- Access Key
- Secret Key
- URL del bucket S3 (oppure Amazon S3)

Se non sai dove trovarle, contatta il tuo amministratore IT.

🚀 Quick Start (5 Minuti)

Step 1: Scarica il Progetto

Apri il terminale (cmd, PowerShell o Terminal) e digita:

git clone https://github.com/pyconetwork/s3_to_folder_sync.git
cd s3_to_folder_sync

Se non hai Git, puoi scaricare il ZIP direttamente da GitHub e estrarlo.

Step 2: Configura il File `.env`

Apri il file .env.example con un editor di testo (Notepad, VS Code, etc.)
Modifica i valori con le tue credenziali:

# Inserisci qui le tue credenziali
S3_ENDPOINT=https://your-s3-endpoint.com
S3_ACCESS_KEY=your_access_key_here
S3_SECRET_KEY=your_secret_key_here
S3_BUCKET=my-bucket-name

Salva il file come .env (senza .example)

📍 Dove trovo queste informazioni?

Credenziale	Dove trovarla
S3_ENDPOINT	URL del tuo server S3 (es: `https://minio.example.com` oppure `https://s3.amazonaws.com`)
S3_ACCESS_KEY	ID chiave di accesso AWS/MinIO
S3_SECRET_KEY	Chiave segreta AWS/MinIO
S3_BUCKET	Nome della cartella su S3 (es: `my-files` oppure `backup-2024`)

⚠️ IMPORTANTE: Non condividere mai il file .env con altri!

Step 3: Crea la Cartella di Destinazione

I file saranno copiati in questa cartella locale. Creala con il nome che preferisci:

# Windows
mkdir data

# Linux/Mac
mkdir -p data

Step 4: Avvia il Progetto

Digita nel terminale:

docker-compose up -d

Il comando:

docker-compose: Avvia l'applicazione in Docker
up: Inizia a eseguire
-d: Esegui in background (il terminale rimane libero)

Aspetta 10-20 secondi mentre il sistema si avvia.

Step 5: Apri la Dashboard

Apri il browser e vai a:

http://localhost:8080

Vedrai una dashboard con:

✅ Stato della sincronizzazione
📊 Numero di file sincronizzati
📈 Ultime modifiche
📋 Log in tempo reale

📊 Dashboard Spiegata

Quando apri la dashboard, vedrai:

🎯 Pannello Superiore (Statistiche)

Card	Significato
Ultima Sync	Quando è stata eseguita l'ultima sincronizzazione
Prossima Sync	Tra quanto verrà eseguita la prossima
File Locali	Quanti file sono stati sincronizzati
Sync Completate	Numero totale di sincronizzazioni riuscite

📋 Pannello Centrale (Log)

Mostra in tempo reale cosa sta facendo il sistema:

File scaricati
Errori (se ce ne sono)
Tempo impiegato

🔄 Pannello Modifiche Recenti

Elenca gli ultimi file aggiunti, modificati o eliminati da S3.

📊 Storico Sincronizzazioni

Una lista delle ultime sincronizzazioni con risultato (✓ OK oppure ✗ Errore).

⚙️ Configurazione Avanzata

Cambiare la Frequenza di Sincronizzazione

Nel file .env, trova questa riga:

SYNC_INTERVAL=300

Questo significa: sincronizza ogni 300 secondi (5 minuti).

Valori comuni:

60 = ogni 1 minuto
300 = ogni 5 minuti ✅ (consigliato)
3600 = ogni ora
86400 = una volta al giorno

Cambiare la Porta della Dashboard

Se la porta 8080 è già occupata, usa un'altra:

WEB_PORT=9000

Poi accedi a http://localhost:9000

Sincronizzare Più Bucket S3 (Avanzato)

Se hai più di un bucket da sincronizzare contemporaneamente:

SYNC_CONFIGS='[
  {"id": "sync1", "bucket": "backup-docs"},
  {"id": "sync2", "bucket": "media-files"},
  {"id": "sync3", "bucket": "archive"}
]'

La dashboard mostrerà tab per switchare tra i diversi sync.

🛑 Fermare il Progetto

Senza perdere i dati:

docker-compose down

I file sincronizzati rimangono nella cartella data/.

Con pulizia completa:

docker-compose down -v

⚠️ Questo elimina anche i dati della dashboard (non i file sincronizzati).

🔧 Risoluzione Problemi

❌ Errore: "Docker not found"

Soluzione: Scarica e installa Docker Desktop

❌ Errore: "Cannot connect to S3"

Verificare:

✓ S3_ENDPOINT è corretto
✓ S3_ACCESS_KEY è corretto
✓ S3_SECRET_KEY è corretto
✓ Il bucket esiste
✓ Hai internet collegato

❌ Dashboard non carica (http://localhost:8080)

Soluzione: Aspetta 20 secondi dall'avvio, poi ricarica la página (F5)

❌ I file non si sincronizzano

Verificare:

✓ Nel log vedi "Sync completata con successo"
✓ La cartella data/ ha i permessi di scrittura
✓ S3_BUCKET è il nome corretto

📧 Notifiche (Opzionale)

Se vuoi ricevere notifiche push quando la sincronizzazione termina, puoi usare Gotify:

GOTIFY_ENABLED=true
GOTIFY_URL=https://your-gotify-server.com
GOTIFY_TOKEN=your-token-here
GOTIFY_PRIORITY=5

Le notifiche arriveranno al tuo browser/telefono quando:

✅ Syncronizzazione completata
❌ Errore during sync

📁 Struttura dei File

Dopo aver avviato, vedrai questa struttura:

s3_to_folder_sync/
├── data/                    ← I TUA FILE SINCRONIZZATI FINISCONO QUI
│   ├── file1.pdf
│   ├── file2.docx
│   └── subfolder/
├── .env                     ← Il tuo file di configurazione
├── docker-compose.yml       ← Non toccare
├── Dockerfile              ← Non toccare
└── README.md               ← Questo file

🎓 Definizioni Semplici

Termine	Significato
S3	Servizio di archiviazione cloud (come un hard disk nel cloud)
Bucket	Una "cartella" su S3
Sincronizzazione	Copiare automaticamente i file
Docker	Un "contenitore" che isola l'applicazione
Dashboard	Una pagina web che mostra le informazioni
Access Key	Username per accedere a S3
Secret Key	Password per accedere a S3

✅ Checklist Finale

Prima di chiedere aiuto, verifica:

Ho Docker installato e funzionante
Ho scaricato il progetto
Ho creato il file .env (non .env.example)
Ho inserito le credenziali S3 corrette
Ho creato la cartella data/
Ho eseguito docker-compose up -d
Aspetto 20 secondi e apro http://localhost:8080

🆘 Hai ancora problemi?

Controlla i log:

docker-compose logs -f

Vedrai in tempo reale cosa sta facendo il sistema. I messaggi di errore te lo diranno!

Chiedi aiuto:

Se il problema persiste, copia l'output dei log e chiedi supporto nel repository.

📚 Documenti Aggiuntivi

.env.example - Tutte le opzioni di configurazione disponibili
CHANGELOG.md - Novità e aggiornamenti

📄 Licenza

Questo progetto è fornito così com'è. Usalo liberamente per i tuoi scopi.

Versione: 2.0.0 (Multi-Sync Ready)
Data: 18 Marzo 2026
Stato: ✅ Production Ready

README.md

📦 S3 to Local Sync Dashboard