++ new project
This commit is contained in:
334
README.md
334
README.md
@@ -1,334 +0,0 @@
|
||||
# 📦 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
|
||||
Reference in New Issue
Block a user