7c456271ac
Update deployment documentation and scripts to deploy to vt.alfacom.it, remove Replit references, and simplify the deployment workflow to two commands: `./push-to-gitlab.sh` and `bash deploy/deploy.sh`, including automated database backups. Replit-Commit-Author: Agent Replit-Commit-Session-Id: 42d8028a-fa71-4ec2-938c-e43eedf7df01 Replit-Commit-Checkpoint-Type: intermediate_checkpoint
514 lines
9.1 KiB
Markdown
514 lines
9.1 KiB
Markdown
# 📘 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: `553da84c94093919d46055d6ec37dfa2a03d0f46`
|
|
- 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
|
|
```
|
|
|
|
**File .env completo:**
|
|
|
|
```bash
|
|
# Database
|
|
DATABASE_URL=postgresql://vigilanza_user:553da84c94093919d46055d6ec37dfa2a03d0f46@localhost:5432/vigilanza_turni
|
|
PGHOST=localhost
|
|
PGPORT=5432
|
|
PGDATABASE=vigilanza_turni
|
|
PGUSER=vigilanza_user
|
|
PGPASSWORD=553da84c94093919d46055d6ec37dfa2a03d0f46
|
|
|
|
# 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
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
BACKUP_FILE="/var/backups/vigilanza-turni/backup_manual_$(date +%Y%m%d_%H%M%S).sql"
|
|
PGPASSWORD=553da84c94093919d46055d6ec37dfa2a03d0f46 \
|
|
pg_dump -h localhost -U vigilanza_user -d vigilanza_turni > $BACKUP_FILE
|
|
gzip $BACKUP_FILE
|
|
echo "Backup salvato: ${BACKUP_FILE}.gz"
|
|
```
|
|
|
|
**Ripristino Backup:**
|
|
```bash
|
|
# 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 | \
|
|
PGPASSWORD=553da84c94093919d46055d6ec37dfa2a03d0f46 \
|
|
psql -h localhost -U vigilanza_user -d vigilanza_turni
|
|
|
|
# Restart applicazione
|
|
pm2 restart vigilanza-turni
|
|
```
|
|
|
|
**Accesso Database:**
|
|
```bash
|
|
PGPASSWORD=553da84c94093919d46055d6ec37dfa2a03d0f46 \
|
|
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
|
|
PGPASSWORD=553da84c94093919d46055d6ec37dfa2a03d0f46 \
|
|
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
|
|
PGPASSWORD=553da84c94093919d46055d6ec37dfa2a03d0f46 \
|
|
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
|
|
BACKUP_FILE=$(ls -t /var/backups/vigilanza-turni/*.gz | head -1)
|
|
gunzip -c $BACKUP_FILE | \
|
|
PGPASSWORD=553da84c94093919d46055d6ec37dfa2a03d0f46 \
|
|
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
|