335 lines
7.9 KiB
Markdown
335 lines
7.9 KiB
Markdown
# 📦 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:
|
|
|
|
1. **Docker** installato sul tuo computer
|
|
- [Scarica Docker da qui](https://www.docker.com/products/docker-desktop)
|
|
- È un programma che permette di eseguire applicazioni in modo isolato
|
|
|
|
2. **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:
|
|
|
|
```bash
|
|
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](https://github.com/pyconetwork/s3_to_folder_sync/archive/refs/heads/main.zip) e estrarlo.
|
|
|
|
### Step 2: Configura il File `.env`
|
|
|
|
1. Apri il file `.env.example` con un **editor di testo** (Notepad, VS Code, etc.)
|
|
2. Modifica i valori con le tue credenziali:
|
|
|
|
```env
|
|
# 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
|
|
```
|
|
|
|
3. **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:
|
|
|
|
```bash
|
|
# Windows
|
|
mkdir data
|
|
|
|
# Linux/Mac
|
|
mkdir -p data
|
|
```
|
|
|
|
### Step 4: Avvia il Progetto
|
|
|
|
Digita nel terminale:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```env
|
|
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:
|
|
|
|
```env
|
|
WEB_PORT=9000
|
|
```
|
|
|
|
Poi accedi a `http://localhost:9000`
|
|
|
|
### Sincronizzare Più Bucket S3 (Avanzato)
|
|
|
|
Se hai **più di un bucket** da sincronizzare contemporaneamente:
|
|
|
|
```env
|
|
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:
|
|
|
|
```bash
|
|
docker-compose down
|
|
```
|
|
|
|
I file sincronizzati rimangono nella cartella `data/`.
|
|
|
|
### Con pulizia completa:
|
|
|
|
```bash
|
|
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](https://www.docker.com/products/docker-desktop)
|
|
|
|
### ❌ Errore: "Cannot connect to S3"
|
|
**Verificare**:
|
|
1. ✓ S3_ENDPOINT è corretto
|
|
2. ✓ S3_ACCESS_KEY è corretto
|
|
3. ✓ S3_SECRET_KEY è corretto
|
|
4. ✓ Il bucket esiste
|
|
5. ✓ 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**:
|
|
1. ✓ Nel log vedi "Sync completata con successo"
|
|
2. ✓ La cartella `data/` ha i permessi di scrittura
|
|
3. ✓ S3_BUCKET è il nome corretto
|
|
|
|
---
|
|
|
|
## 📧 Notifiche (Opzionale)
|
|
|
|
Se vuoi ricevere **notifiche push** quando la sincronizzazione termina, puoi usare **Gotify**:
|
|
|
|
```env
|
|
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:
|
|
|
|
```bash
|
|
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`](.env.example) - Tutte le opzioni di configurazione disponibili
|
|
- [CHANGELOG.md](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
|