7.9 KiB
📦 S3 to Local Sync Dashboard
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.examplecon 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 Dockerup: 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 minuto300= ogni 5 minuti ✅ (consigliato)3600= ogni ora86400= 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