VigilanzaTurni/DEPLOYMENT.md

# 📘 Deployment Guide - VigilanzaTurni

Guida completa deployment sistema VigilanzaTurni su vt.alfacom.it

---

## 📋 Indice

1. [Overview](#overview)
2. [Prerequisiti](#prerequisiti)
3. [Setup Iniziale](#setup-iniziale)
4. [Configurazione](#configurazione)
5. [Deployment](#deployment)
6. [Manutenzione](#manutenzione)
7. [Troubleshooting](#troubleshooting)

---

## Overview

**Architettura Deployment:**
```
Replit/Local Dev
    ↓ (git push)
GitLab Repository
    ↓ (manual deploy)
AlmaLinux 9 Server
    ↓
https://vt.alfacom.it (Production)
```

**Stack Produzione:**
- OS: AlmaLinux 9
- Runtime: Node.js 20
- Database: PostgreSQL 15
- Process Manager: PM2
- Web Server: Nginx (reverse proxy)
- SSL: Let's Encrypt (Certbot)

---

## Prerequisiti

### Server Requirements
- AlmaLinux 9 (fresh install)
- Min 2GB RAM, 20GB disk
- Accesso root SSH
- Dominio: vt.alfacom.it (DNS configurato)

### Locale Requirements
- Git installato
- SSH key configurata
- Accesso repository GitLab

---

## Setup Iniziale

### 1. Preparazione Server

```bash
# SSH nel server
ssh root@vt.alfacom.it

# Clone repository
cd /var/www
git clone https://git.alfacom.it/marco/VigilanzaTurni.git vigilanza-turni
cd vigilanza-turni

# Esegui setup automatico
sudo bash deploy/setup-server.sh
```

Lo script `setup-server.sh` installa automaticamente:

✅ **Node.js 20**
- Runtime JavaScript/TypeScript
- npm package manager

✅ **PostgreSQL 15**
- Database relazionale
- User: `vigilanza_user`
- Password: **Generata automaticamente** (salvata in `/root/.vigilanza_db_password`)
- Database: `vigilanza_turni`

✅ **PM2**
- Process manager Node.js
- Auto-restart on crash
- Log management
- Startup script

✅ **Nginx**
- Reverse proxy
- SSL termination
- Static files serving
- Gzip compression

✅ **Git**
- Version control

✅ **Firewall**
- HTTP (80) aperto
- HTTPS (443) aperto

✅ **Certbot**
- Let's Encrypt SSL certificates

### 2. Configurazione Nginx

```bash
# Copia configurazione
sudo cp deploy/nginx.conf /etc/nginx/conf.d/vigilanza-turni.conf

# Test configurazione
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx
```

### 3. SSL Certificate

```bash
# Ottieni certificato Let's Encrypt
sudo certbot --nginx -d vt.alfacom.it

# Auto-renewal (crontab)
sudo certbot renew --dry-run
```

### 4. Configurazione Ambiente

```bash
cd /var/www/vigilanza-turni

# Copia template
cp .env.production.example .env

# Edita .env
nano .env
```

**Recupera password e crea .env:**

```bash
# Recupera password da file sicuro
DB_PASS=$(grep PGPASSWORD /root/.vigilanza_db_password | cut -d= -f2)

# Crea .env con password reale (non shell var)
cat > .env << EOF
# Database
DATABASE_URL=postgresql://vigilanza_user:${DB_PASS}@localhost:5432/vigilanza_turni
PGHOST=localhost
PGPORT=5432
PGDATABASE=vigilanza_turni
PGUSER=vigilanza_user
PGPASSWORD=${DB_PASS}

# Session (genera nuovo)
SESSION_SECRET=$(openssl rand -base64 32)

# Application
NODE_ENV=production
PORT=5000
APP_URL=https://vt.alfacom.it

# Backup
BACKUP_ENABLED=true
BACKUP_DIR=/var/backups/vigilanza-turni
BACKUP_RETENTION_DAYS=30

# Logging
LOG_LEVEL=info
EOF

echo "✅ File .env creato con password sicura"
```

**Verifica .env creato:**
```bash
cat .env | grep DATABASE_URL
# Deve mostrare password reale, non ${DB_PASS}
```

---

## Deployment

### Workflow Semplificato (2 comandi)

#### 1. Push da Replit/Local

```bash
./push-to-gitlab.sh
```

Questo script:
- Mostra modifiche da committare
- Chiede conferma
- Esegue git add + commit + push
- Mostra istruzioni deployment

#### 2. Deploy su Server

```bash
ssh root@vt.alfacom.it "cd /var/www/vigilanza-turni && bash deploy/deploy.sh"
```

Lo script `deploy.sh` esegue automaticamente:

1. **Backup Database Pre-Deploy**
   - Dump PostgreSQL completo
   - Compressione gzip
   - Salvataggio in `/var/backups/vigilanza-turni/`
   - Pulizia backup > 30 giorni

2. **Pull Modifiche**
   - Git pull da GitLab

3. **Build Applicazione**
   - `npm ci` (install deps)
   - `npm run build` (Vite build)
   - `npm run db:push` (migrations)
   - `npm prune --production` (cleanup)

4. **Restart Applicazione**
   - PM2 reload graceful
   - Health check
   - Log output

5. **Rollback Automatico**
   - Se deploy fallisce, ripristina ultimo backup DB

---

## Manutenzione

### Gestione PM2

```bash
# Status
pm2 status

# Logs real-time
pm2 logs vigilanza-turni

# Logs storici
pm2 logs vigilanza-turni --lines 100

# Restart
pm2 restart vigilanza-turni

# Stop
pm2 stop vigilanza-turni

# Info applicazione
pm2 show vigilanza-turni

# Monitoring
pm2 monit
```

### Gestione Database

**Backup Manuale:**
```bash
# Carica password da file sicuro
export $(cat /root/.vigilanza_db_password | xargs)

BACKUP_FILE="/var/backups/vigilanza-turni/backup_manual_$(date +%Y%m%d_%H%M%S).sql"
pg_dump -h localhost -U vigilanza_user -d vigilanza_turni > $BACKUP_FILE
gzip $BACKUP_FILE
echo "Backup salvato: ${BACKUP_FILE}.gz"
```

**Ripristino Backup:**
```bash
# Carica password da file sicuro
export $(cat /root/.vigilanza_db_password | xargs)

# Lista backup disponibili
ls -lht /var/backups/vigilanza-turni/*.gz

# Ripristina specifico backup
BACKUP_FILE="/var/backups/vigilanza-turni/backup_20250116_143022.sql.gz"
gunzip -c $BACKUP_FILE | psql -h localhost -U vigilanza_user -d vigilanza_turni

# Restart applicazione
pm2 restart vigilanza-turni
```

**Accesso Database:**
```bash
# Carica password da file sicuro
export $(cat /root/.vigilanza_db_password | xargs)

psql -h localhost -U vigilanza_user -d vigilanza_turni
```

### Log Management

**Nginx Logs:**
```bash
# Access log
tail -f /var/log/nginx/vigilanza-turni-access.log

# Error log
tail -f /var/log/nginx/vigilanza-turni-error.log

# Analisi traffico
cat /var/log/nginx/vigilanza-turni-access.log | \
  awk '{print $1}' | sort | uniq -c | sort -rn | head -10
```

**PM2 Logs:**
```bash
# Real-time
pm2 logs vigilanza-turni

# Last 50 lines
pm2 logs vigilanza-turni --lines 50 --nostream

# Flush logs
pm2 flush vigilanza-turni
```

### SSL Certificate Renewal

```bash
# Test renewal
sudo certbot renew --dry-run

# Force renewal
sudo certbot renew --force-renewal

# Check expiration
sudo certbot certificates
```

### System Updates

```bash
# Update sistema
sudo dnf update -y

# Update Node.js packages
cd /var/www/vigilanza-turni
npm outdated
npm update

# Rebuild dopo update
npm run build
pm2 restart vigilanza-turni
```

---

## Troubleshooting

### Applicazione non Risponde

```bash
# 1. Check PM2 status
pm2 status

# 2. Check logs
pm2 logs vigilanza-turni --lines 100

# 3. Restart
pm2 restart vigilanza-turni

# 4. Check Nginx
sudo nginx -t
sudo systemctl status nginx
sudo systemctl reload nginx

# 5. Check firewall
sudo firewall-cmd --list-all
```

### Errore Database

```bash
# 1. Verifica connessione
export $(cat /root/.vigilanza_db_password | xargs)
psql -h localhost -U vigilanza_user -d vigilanza_turni -c "SELECT version();"

# 2. Check PostgreSQL
sudo systemctl status postgresql
sudo tail -f /var/lib/pgsql/data/log/postgresql-*.log

# 3. Restart PostgreSQL
sudo systemctl restart postgresql

# 4. Verifica .env
cat /var/www/vigilanza-turni/.env | grep DATABASE_URL
```

### Build Fallito

```bash
# 1. Clean build
cd /var/www/vigilanza-turni
rm -rf node_modules dist

# 2. Reinstall
npm ci

# 3. Rebuild
npm run build

# 4. Check errors
npm run build 2>&1 | tee build.log

# 5. Restart
pm2 restart vigilanza-turni
```

### SSL Issues

```bash
# 1. Check certificate
sudo certbot certificates

# 2. Renew certificate
sudo certbot renew --force-renewal

# 3. Reload Nginx
sudo systemctl reload nginx

# 4. Check SSL config
sudo nginx -t
```

### Performance Issues

```bash
# 1. Check server resources
htop
df -h
free -m

# 2. PM2 monitoring
pm2 monit

# 3. Nginx access log analysis
sudo tail -f /var/log/nginx/vigilanza-turni-access.log

# 4. Database performance
export $(cat /root/.vigilanza_db_password | xargs)
psql -h localhost -U vigilanza_user -d vigilanza_turni -c \
  "SELECT query, calls, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
```

### Rollback Completo

```bash
# 1. Stop applicazione
pm2 stop vigilanza-turni

# 2. Ripristina database
export $(cat /root/.vigilanza_db_password | xargs)
BACKUP_FILE=$(ls -t /var/backups/vigilanza-turni/*.gz | head -1)
gunzip -c $BACKUP_FILE | psql -h localhost -U vigilanza_user -d vigilanza_turni

# 3. Git rollback
cd /var/www/vigilanza-turni
git log --oneline -10  # Trova commit precedente
git reset --hard <commit-hash>

# 4. Rebuild
npm ci
npm run build

# 5. Restart
pm2 restart vigilanza-turni
```

---

## Checklist Deployment

### Pre-Deployment
- [ ] Backup database eseguito
- [ ] Test locali passati
- [ ] Git push completato
- [ ] Server accessibile

### During Deployment
- [ ] `./push-to-gitlab.sh` eseguito
- [ ] SSH server funzionante
- [ ] `bash deploy/deploy.sh` completato senza errori
- [ ] Health check PM2 OK

### Post-Deployment
- [ ] Applicazione risponde: https://vt.alfacom.it
- [ ] Login funzionante
- [ ] Database accessibile
- [ ] Logs puliti (no errori)
- [ ] SSL certificate valido

---

## Sicurezza

### Best Practices
1. ✅ SSL/TLS sempre attivo
2. ✅ Firewall configurato
3. ✅ Password database sicura
4. ✅ Backup automatici attivi
5. ✅ Logs monitorati
6. ✅ Sistema aggiornato regolarmente

### Hardening Suggerito
- Fail2ban per brute-force protection
- SSH key-only authentication
- Database backup off-site
- Monitoring con Prometheus/Grafana
- Alert via email/Telegram

---

## Contatti

**Support:** Marco Alfacom  
**Repository:** https://git.alfacom.it/marco/VigilanzaTurni  
**Production:** https://vt.alfacom.it

---

**Ultima revisione:** Ottobre 2025