VigilanzaTurni/DEPLOYMENT.md

# 🚀 Guida Deployment VigilanzaTurni

Deployment automatico da Replit → GitLab → Server AlmaLinux 9

## 📋 Indice

1. [Prerequisiti](#prerequisiti)
2. [Setup Iniziale Server](#setup-iniziale-server)
3. [Configurazione GitLab](#configurazione-gitlab)
4. [Configurazione Replit](#configurazione-replit)
5. [Primo Deployment](#primo-deployment)
6. [Deployment Automatico](#deployment-automatico)
7. [Manutenzione](#manutenzione)
8. [Troubleshooting](#troubleshooting)

---

## 1. Prerequisiti

### Server AlmaLinux 9
- Server con accesso root/sudo
- Almeno 2GB RAM
- 20GB storage
- Indirizzo IP pubblico
- Dominio configurato (es. vigilanza.tuodominio.it)

### Account e Accessi
- Account GitLab su git.alfacom.it
- SSH access al server
- Replit account con questo progetto

---

## 2. Setup Iniziale Server

### 2.1 Connessione al Server

```bash
ssh root@ip-del-tuo-server
```

### 2.2 Esecuzione Script Setup

```bash
# Download script setup
curl -o setup-server.sh https://git.alfacom.it/marco/VigilanzaTurni/-/raw/main/deploy/setup-server.sh

# Rendi eseguibile
chmod +x setup-server.sh

# Esegui setup
sudo bash setup-server.sh
```

Lo script installerà:
- ✅ Node.js 20 LTS
- ✅ PostgreSQL 15
- ✅ PM2 (process manager)
- ✅ Nginx (reverse proxy)
- ✅ Git
- ✅ Firewall configurato
- ✅ Certbot (per SSL)

### 2.3 Configurazione Database

Lo script crea automaticamente:
- Database: `vigilanza_turni`
- User: `vigilanza_user`
- Password: **Generata automaticamente** (mostrata a fine setup)

⚠️ **IMPORTANTE**: Salva la password mostrata al termine del setup!

```bash
# La password è salvata anche in:
cat /root/.vigilanza_db_password

# Se persa, puoi cambiarla con:
sudo -u postgres psql
ALTER USER vigilanza_user WITH PASSWORD 'NuovaPasswordSicura123!';
\q
```

### 2.4 Configurazione SSL

```bash
# Sostituisci tuodominio.it con il tuo dominio
sudo certbot --nginx -d vigilanza.tuodominio.it
```

Certbot configurerà automaticamente:
- Certificato SSL Let's Encrypt
- Redirect HTTP → HTTPS
- Auto-rinnovo certificato

---

## 3. Configurazione GitLab

### 3.1 Variabili CI/CD

Vai su GitLab: **Settings → CI/CD → Variables**

Aggiungi queste variabili:

| Variabile | Valore | Protected | Masked |
|-----------|--------|-----------|--------|
| `SSH_PRIVATE_KEY` | La tua chiave SSH privata | ✅ | ✅ |
| `DEPLOY_HOST` | IP o hostname del server | ✅ | ❌ |
| `DEPLOY_USER` | `root` o utente deploy | ✅ | ❌ |
| `DEPLOY_DOMAIN` | `vigilanza.tuodominio.it` | ✅ | ❌ |

#### Generare SSH Key

```bash
# Sul tuo computer locale
ssh-keygen -t ed25519 -C "gitlab-deploy" -f ~/.ssh/gitlab-deploy

# Copia chiave pubblica sul server
ssh-copy-id -i ~/.ssh/gitlab-deploy.pub root@ip-del-server

# Copia chiave privata (contenuto completo)
cat ~/.ssh/gitlab-deploy
# Copia output e incolla in GitLab come SSH_PRIVATE_KEY
```

### 3.2 Abilitare GitLab Runner

Assicurati che il progetto abbia accesso a un Runner GitLab:
- Vai su **Settings → CI/CD → Runners**
- Abilita un Shared Runner o configura un Specific Runner

---

## 4. Configurazione Replit

### 4.1 Configurare Git Remote

```bash
# In Replit Shell
git remote add production https://git.alfacom.it/marco/VigilanzaTurni.git

# Verifica
git remote -v
```

### 4.2 Autenticazione GitLab

Crea Personal Access Token su GitLab:
1. GitLab → **User Settings → Access Tokens**
2. Nome: `Replit Deploy`
3. Scopes: `write_repository`
4. Copia il token

In Replit, salva token nei Secrets:
```bash
# Secrets → Add new secret
Name: GITLAB_TOKEN
Value: <il-tuo-token>
```

### 4.3 Script Push Automatico

Crea file `push-to-gitlab.sh` in Replit:

```bash
#!/bin/bash
git add .
git commit -m "Deploy: $(date '+%Y-%m-%d %H:%M:%S')"
git push production main
```

---

## 5. Primo Deployment

### 5.1 Configurazione .env Produzione

Sul server:

```bash
cd /var/www/vigilanza-turni
cp .env.production.example .env
nano .env
```

Configura usando la password PostgreSQL generata durante setup:

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

# Configura .env
DATABASE_URL=postgresql://vigilanza_user:${DB_PASS}@localhost:5432/vigilanza_turni
SESSION_SECRET=$(openssl rand -base64 32)
REPLIT_DOMAINS=vigilanza.tuodominio.it
```

### 5.2 Configurazione Nginx

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

# Modifica con il tuo dominio
sudo nano /etc/nginx/conf.d/vigilanza-turni.conf
# Sostituisci "tuodominio.it" con il tuo dominio

# Test configurazione
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx
```

### 5.3 Clone Repository Iniziale

```bash
cd /var/www/vigilanza-turni
git clone https://git.alfacom.it/marco/VigilanzaTurni.git .
```

### 5.4 Primo Deploy Manuale

```bash
bash deploy/deploy.sh
```

Verifica:
```bash
pm2 status
pm2 logs vigilanza-turni
```

---

## 6. Deployment Automatico

### 6.1 Push da Replit

```bash
# In Replit Shell
bash push-to-gitlab.sh
```

### 6.2 Trigger Pipeline GitLab

1. Vai su GitLab → **CI/CD → Pipelines**
2. La pipeline parte automaticamente
3. Clicca su `deploy_production` quando vuoi deployare
4. Il deploy avviene in ~3-5 minuti

### 6.3 Flusso Automatico

```mermaid
Replit → Git Push → GitLab → CI/CD Pipeline → Deploy Server
```

**Stages:**
1. 🏗️ **Build** - Compila TypeScript e Vite
2. 🧪 **Test** - Esegue linting
3. 🚀 **Deploy** - Deployment su server (manuale)

---

## 7. Manutenzione

### 7.1 Monitoring

```bash
# Status applicazione
pm2 status

# Logs real-time
pm2 logs vigilanza-turni

# Logs ultimi 100 righe
pm2 logs vigilanza-turni --lines 100

# Metriche sistema
pm2 monit
```

### 7.2 Backup Database

```bash
# Backup manuale
sudo -u postgres pg_dump vigilanza_turni > backup_$(date +%Y%m%d).sql

# Restore
sudo -u postgres psql vigilanza_turni < backup_20250110.sql
```

### 7.3 Aggiornamenti Sistema

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

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

# Restart
pm2 restart vigilanza-turni
```

### 7.4 SSL Certificate Renewal

Certbot rinnova automaticamente, ma puoi forzare:

```bash
sudo certbot renew --dry-run  # Test
sudo certbot renew            # Rinnovo reale
sudo systemctl reload nginx
```

---

## 8. Troubleshooting

### App non risponde

```bash
# Check PM2
pm2 status
pm2 restart vigilanza-turni

# Check logs
pm2 logs vigilanza-turni --lines 50

# Check Nginx
sudo nginx -t
sudo systemctl status nginx
```

### Database Connection Error

```bash
# Verifica PostgreSQL
sudo systemctl status postgresql
sudo -u postgres psql -c "SELECT version();"

# Test connessione
psql "postgresql://vigilanza_user:password@localhost:5432/vigilanza_turni" -c "SELECT NOW();"
```

### SSL Certificate Issues

```bash
# Test SSL
sudo certbot certificates

# Rinnovo manuale
sudo certbot renew --force-renewal
sudo systemctl reload nginx
```

### Rollback Emergenza

In GitLab → CI/CD → Pipelines → clicca su "rollback"

Oppure manuale:

```bash
cd /var/www/vigilanza-turni
git log --oneline -10  # Trova commit precedente
git checkout <commit-hash>
bash deploy/deploy.sh
```

---

## 📞 Supporto

### Logs Utili

```bash
# PM2 logs
pm2 logs vigilanza-turni --lines 200

# Nginx logs
sudo tail -f /var/log/nginx/vigilanza-turni-error.log
sudo tail -f /var/log/nginx/vigilanza-turni-access.log

# System logs
sudo journalctl -u nginx -f
sudo journalctl -xe
```

### Comandi Rapidi

```bash
# Restart completo
pm2 restart vigilanza-turni && sudo systemctl reload nginx

# Deploy forzato
cd /var/www/vigilanza-turni && git pull && bash deploy/deploy.sh

# Clear cache PM2
pm2 delete vigilanza-turni
pm2 start npm --name vigilanza-turni -- start
pm2 save
```

---

## ✅ Checklist Post-Deployment

- [ ] Applicazione accessibile su https://tuodominio.it
- [ ] SSL certificate valido (lucchetto verde)
- [ ] Login funzionante
- [ ] Database connesso
- [ ] Logs puliti (no errori critici)
- [ ] PM2 status: online
- [ ] Backup database configurato
- [ ] Monitoring attivo

---

**Ultima modifica:** 2025-10-11  
**Versione:** 1.0