VigilanzaTurni/GITLAB-DEPLOY.md

🚀 VigilanzaTurni - Guida Deployment GitLab

Sistema di deployment automatico con versioning semantico e backup database.

---

📋 Indice

1. Configurazione Iniziale
2. Come Fare il Deploy
3. Versioning Semantico
4. Backup Database
5. 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:

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

Contenuto git.env:

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:

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

---

🚀 Come Fare il Deploy

Metodo Rapido (Consigliato)

# 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

# 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

./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à

./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

./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:

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

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

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

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

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

# 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

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

Fine Settimana (Nuove Feature)

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

Release Maggiori (Milestone)

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