VigilanzaTurni/GITLAB-DEPLOY.md

# 🚀 VigilanzaTurni - Guida Deployment GitLab

Sistema di deployment automatico con **versioning semantico** e **backup database**.

---

## 📋 Indice

1. [Configurazione Iniziale](#configurazione-iniziale)
2. [Come Fare il Deploy](#come-fare-il-deploy)
3. [Versioning Semantico](#versioning-semantico)
4. [Backup Database](#backup-database)
5. [Troubleshooting](#troubleshooting)

---

## 🔧 Configurazione Iniziale

### 1. Crea Personal Access Token su GitLab

1. Vai su **GitLab** → **Preferenze** → **Access Tokens**
   - URL: https://gitlab.com/-/profile/personal_access_tokens

2. Crea nuovo token con nome: `VigilanzaTurni Deploy`

3. Seleziona questi **permessi** (scopes):
   - ✅ `api` - Accesso completo API
   - ✅ `read_repository` - Lettura repository
   - ✅ `write_repository` - Scrittura repository

4. **Salva il token** (lo vedrai una sola volta!)

### 2. Configura git.env

Crea il file `git.env` nella root del progetto:

```bash
# Il file git.env è già presente come template
nano git.env
```

Contenuto `git.env`:

```bash
GITLAB_USER=tuo-username
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_REPO=https://gitlab.com/tuo-username/vigilanzaturni.git
GITLAB_BRANCH=main
```

**⚠️ IMPORTANTE**: 
- Il file `git.env` è già in `.gitignore` - **non verrà mai committato**
- Conserva il token in un posto sicuro (password manager)

### 3. Verifica Repository GitLab

Assicurati che il repository esista su GitLab:

```bash
# Crea repository su GitLab web UI
# Oppure usa GitLab CLI
```

---

## 🚀 Come Fare il Deploy

### Metodo Rapido (Consigliato)

```bash
# Rendi eseguibile (solo prima volta)
chmod +x push-gitlab.sh

# Deploy patch (bug fix, piccole modifiche)
./push-gitlab.sh

# Deploy minor (nuove funzionalità)
./push-gitlab.sh minor

# Deploy major (breaking changes)
./push-gitlab.sh major
```

### Metodo Completo

```bash
# Usa lo script principale per maggior controllo
./deploy-to-gitlab.sh [patch|minor|major]
```

---

## 📊 Versioning Semantico

Il sistema usa **Semantic Versioning 2.0.0**: `MAJOR.MINOR.PATCH`

### Formato Versione: `X.Y.Z`

| Componente | Quando Incrementare | Esempio |
|------------|---------------------|---------|
| **MAJOR (X)** | Breaking changes, API incompatibili | 1.5.3 → **2.0.0** |
| **MINOR (Y)** | Nuove funzionalità retrocompatibili | 1.5.3 → **1.6.0** |
| **PATCH (Z)** | Bug fix, piccole correzioni | 1.5.3 → **1.5.4** |

### Esempi Pratici

#### PATCH (default) - Bug fix
```bash
./push-gitlab.sh          # 1.0.0 → 1.0.1
./push-gitlab.sh patch    # 1.0.1 → 1.0.2
```

**Quando usare**:
- ✅ Correzione bug
- ✅ Typo nel codice
- ✅ Performance minori
- ✅ Aggiornamento dipendenze patch

#### MINOR - Nuove funzionalità
```bash
./push-gitlab.sh minor    # 1.0.5 → 1.1.0
```

**Quando usare**:
- ✅ Nuova pagina/sezione
- ✅ Nuova API endpoint
- ✅ Feature richiesta da cliente
- ✅ Miglioramento UX significativo

#### MAJOR - Breaking changes
```bash
./push-gitlab.sh major    # 1.5.2 → 2.0.0
```

**Quando usare**:
- ✅ Cambio architettura database
- ✅ Rimozione API/endpoint
- ✅ Cambio sistema autenticazione
- ✅ Migrazione framework

---

## 💾 Backup Database

### Automatico ad Ogni Deploy

Lo script **crea automaticamente** un backup del database:

```
database-backups/
  └── vigilanzaturni_v1.0.1_20250117_143022.sql.gz
  └── vigilanzaturni_v1.0.2_20250117_150315.sql.gz
  └── vigilanzaturni_v1.1.0_20250118_091145.sql.gz
```

### Formato Nome File

```
vigilanzaturni_v{VERSION}_{TIMESTAMP}.sql.gz
```

- **VERSION**: Versione deployment (es. 1.0.1)
- **TIMESTAMP**: Data e ora (YYYYMMDD_HHMMSS)

### Retention Policy

- ✅ Compressi con gzip (risparmio spazio ~90%)
- ✅ Mantiene ultimi **10 backup** automaticamente
- ✅ Backup più vecchi eliminati automaticamente

### Ripristino Manuale

Se necessario ripristinare un backup:

```bash
# 1. Decomprimi
gunzip database-backups/vigilanzaturni_v1.0.1_20250117_143022.sql.gz

# 2. Ripristina
psql $DATABASE_URL < database-backups/vigilanzaturni_v1.0.1_20250117_143022.sql
```

---

## 🔍 Troubleshooting

### ❌ Errore: "git.env non trovato"

**Soluzione**:
```bash
# Crea git.env e configura credenziali
nano git.env
```

### ❌ Errore: "Authentication failed"

**Possibili cause**:
1. Token GitLab scaduto
2. Token senza permessi corretti
3. Username errato

**Soluzione**:
```bash
# 1. Verifica credenziali in git.env
cat git.env

# 2. Crea nuovo token su GitLab
# https://gitlab.com/-/profile/personal_access_tokens

# 3. Aggiorna GITLAB_TOKEN in git.env
```

### ❌ Errore: "Remote repository not found"

**Soluzione**:
```bash
# Verifica URL repository in git.env
# Deve essere: https://gitlab.com/USERNAME/REPO.git

# Verifica che il repository esista su GitLab
```

### ❌ Backup Database Fallito

**Soluzione**:
```bash
# Verifica DATABASE_URL
echo $DATABASE_URL

# Verifica pg_dump installato
which pg_dump

# Test manuale backup
pg_dump $DATABASE_URL > test-backup.sql
```

### ⚠️ Warning: "Push failed"

**Possibili cause**:
1. Repository protetto (protected branch)
2. Permessi insufficienti
3. Conflitti git

**Soluzione**:
```bash
# 1. Verifica branch protection su GitLab
# Settings → Repository → Protected Branches

# 2. Verifica permessi token (deve essere Maintainer/Owner)

# 3. Forza push (con cautela!)
git push gitlab main --force
```

---

## 📈 Workflow Consigliato

### Sviluppo Giornaliero

```bash
# Ogni bug fix o piccola modifica
./push-gitlab.sh            # 1.0.0 → 1.0.1 → 1.0.2
```

### Fine Settimana (Nuove Feature)

```bash
# Dopo aver completato una feature
./push-gitlab.sh minor      # 1.0.5 → 1.1.0
```

### Release Maggiori (Milestone)

```bash
# Dopo cambiamenti architetturali importanti
./push-gitlab.sh major      # 1.5.2 → 2.0.0
```

---

## 📝 File Generati

| File | Descrizione | Committato su Git |
|------|-------------|-------------------|
| `git.env` | Credenziali GitLab | ❌ No (in .gitignore) |
| `version.json` | Versione corrente | ✅ Sì |
| `database-backups/*.sql.gz` | Backup DB | ❌ No (in .gitignore) |
| `deploy-to-gitlab.sh` | Script deployment | ✅ Sì |
| `push-gitlab.sh` | Helper script | ✅ Sì |

---

## 🎯 Best Practices

### ✅ DO

- Fai deploy **frequenti** (patch)
- Usa **minor** per nuove feature complete
- Usa **major** solo per breaking changes
- Testa localmente prima del deploy
- Verifica backup database dopo deploy importante

### ❌ DON'T

- Non committare `git.env` (già protetto)
- Non saltare versioni manualmente
- Non modificare `version.json` manualmente
- Non eliminare backup recenti manualmente

---

## 📞 Supporto

In caso di problemi:

1. Controlla version.json: `cat version.json`
2. Verifica configurazione: `cat git.env`
3. Testa connessione GitLab manualmente
4. Controlla se il repository esiste

---

**Versione Documento**: 1.0.0  
**Ultimo Aggiornamento**: 2025-01-17  
**Compatibilità**: VigilanzaTurni v1.0.0+