VigilanzaTurni/DEPLOYMENT.md

📘 Deployment Guide - VigilanzaTurni

Guida completa deployment sistema VigilanzaTurni su vt.alfacom.it

---

📋 Indice

1. Overview
2. Prerequisiti
3. Setup Iniziale
4. Configurazione
5. Deployment
6. Manutenzione
7. 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

# 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

# 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

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

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

4. Configurazione Ambiente

cd /var/www/vigilanza-turni

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

# Edita .env
nano .env

Recupera password e crea .env:

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

cat .env | grep DATABASE_URL
# Deve mostrare password reale, non ${DB_PASS}

---

Deployment

Workflow Semplificato (2 comandi)

1. Push da Replit/Local

./push-to-gitlab.sh

Questo script:

• Mostra modifiche da committare
• Chiede conferma
• Esegue git add + commit + push
• Mostra istruzioni deployment

2. Deploy su Server

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

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

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

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

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

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

# 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

# Test renewal
sudo certbot renew --dry-run

# Force renewal
sudo certbot renew --force-renewal

# Check expiration
sudo certbot certificates

System Updates

# 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

# 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

# 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

# 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

# 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

# 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

# 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