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