VigilanzaTurni/DEPLOYMENT.md

🚀 Guida Deployment VigilanzaTurni

Deployment automatico da Replit → GitLab → Server AlmaLinux 9

📋 Indice

1. Prerequisiti
2. Setup Iniziale Server
3. Configurazione GitLab
4. Configurazione Replit
5. Primo Deployment
6. Deployment Automatico
7. Manutenzione
8. 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

ssh root@ip-del-tuo-server

2.2 Esecuzione Script Setup

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

# 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

# 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

# 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

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

# Secrets → Add new secret
Name: GITLAB_TOKEN
Value: <il-tuo-token>

4.3 Script Push Automatico

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

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

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

Configura usando la password PostgreSQL generata durante setup:

# 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

# 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

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

5.4 Primo Deploy Manuale

bash deploy/deploy.sh

Verifica:

pm2 status
pm2 logs vigilanza-turni

---

6. Deployment Automatico

6.1 Push da Replit

# 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

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

# 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

# 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

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

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

---

8. Troubleshooting

App non risponde

# 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

# 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

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

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

---

📞 Supporto

Logs Utili

# 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

# 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