====== Runbook: systemd ======

<WRAP round info>
**Durata:** ~10 minuti \\
**Ruolo:** Amministratore Linux \\
**Prerequisito:** root/sudo, .NET 8 Runtime
</WRAP>

Eseguire Data Gateway come servizio systemd su Linux.

----

===== Workflow =====

<mermaid>
flowchart TD
    A[Start] --> B[Installare Gateway]
    B --> C[Creare Service-Unit]
    C --> D[systemctl enable]
    D --> E[systemctl start]
    E --> F[Health Check]
    F --> G{OK?}
    G -->|Si| H[Finito]
    G -->|No| I[controllare journalctl]

    style H fill:#e8f5e9
    style I fill:#ffebee
</mermaid>

----

===== 1. Installare Gateway =====

<code bash>
# Creare directory
sudo mkdir -p /opt/data-gateway
sudo chown $USER:$USER /opt/data-gateway

# Copiare file
cp -r ./publish/* /opt/data-gateway/

# Rendere eseguibile
chmod +x /opt/data-gateway/WvdS.WebAPI.Data.Gateway.Api

# Modificare configurazione
sudo nano /opt/data-gateway/appsettings.json
</code>

----

===== 2. Creare utente =====

<code bash>
# Utente dedicato per il servizio
sudo useradd --system --no-create-home --shell /sbin/nologin datagateway

# Impostare permessi
sudo chown -R datagateway:datagateway /opt/data-gateway
</code>

----

===== 3. Creare systemd Unit =====

<code bash>
sudo nano /etc/systemd/system/data-gateway.service
</code>

**Contenuto:**

<code ini>
[Unit]
Description=WvdS Data Gateway
Documentation=https://wiki.example.com/data-gateway
After=network.target

[Service]
Type=notify
User=datagateway
Group=datagateway
WorkingDirectory=/opt/data-gateway
ExecStart=/opt/data-gateway/WvdS.WebAPI.Data.Gateway.Api
Restart=always
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=data-gateway
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

# Sicurezza
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/opt/data-gateway/logs
ReadWritePaths=/opt/data-gateway/data

# Limiti
LimitNOFILE=65536
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target
</code>

----

===== 4. Attivare servizio =====

<code bash>
# Ricaricare systemd
sudo systemctl daemon-reload

# Attivare autostart
sudo systemctl enable data-gateway

# Avviare servizio
sudo systemctl start data-gateway

# Controllare stato
sudo systemctl status data-gateway
</code>

----

===== 5. Health Check =====

<code bash>
# Attendere che sia pronto
sleep 5

# Health Check
curl -s http://localhost:5000/health
# Risposta attesa: "Healthy"

# Test API
curl -s http://localhost:5000/api/v1/dsn/demo/tables | head
</code>

----

===== 6. Visualizzare Log =====

<code bash>
# Log attuali
sudo journalctl -u data-gateway -n 50 --no-pager

# Live-Tail
sudo journalctl -u data-gateway -f

# Da oggi
sudo journalctl -u data-gateway --since today

# Solo errori
sudo journalctl -u data-gateway -p err
</code>

----

===== 7. Checklist =====

| # | Punto di verifica | v |
|---|-----------|---|
| 1 | .NET 8 installato | ☐ |
| 2 | Gateway in /opt/data-gateway | ☐ |
| 3 | Service-User creato | ☐ |
| 4 | Unit-file creato | ☐ |
| 5 | Servizio enabled | ☐ |
| 6 | Servizio avviato | ☐ |
| 7 | Health Check OK | ☐ |

----

===== Comandi Servizio =====

| Comando | Descrizione |
|--------|--------------|
| ''systemctl start data-gateway'' | Avviare |
| ''systemctl stop data-gateway'' | Fermare |
| ''systemctl restart data-gateway'' | Riavviare |
| ''systemctl status data-gateway'' | Stato |
| ''systemctl enable data-gateway'' | Autostart on |
| ''systemctl disable data-gateway'' | Autostart off |

----

===== Troubleshooting =====

| Problema | Causa | Soluzione |
|---------|---------|--------|
| ''code=exited, status=203'' | Percorso sbagliato | verificare ExecStart |
| ''code=exited, status=1'' | Errore config | controllare journalctl |
| ''Permission denied'' | Permessi errati | controllare chown |
| ''Address already in use'' | Porta occupata | altra porta o killare processo |

**Analisi errori dettagliata:**

<code bash>
# Testare eseguibile direttamente
sudo -u datagateway /opt/data-gateway/WvdS.WebAPI.Data.Gateway.Api

# Problemi SELinux (RHEL/CentOS)
sudo ausearch -m avc -ts recent
sudo setsebool -P httpd_can_network_connect 1
</code>

----

===== Cambiare porta =====

In ''appsettings.json'':

<code json>
{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:8080"
      }
    }
  }
}
</code>

**Aprire firewall:**

<code bash>
# firewalld (RHEL/CentOS)
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

# ufw (Ubuntu/Debian)
sudo ufw allow 8080/tcp
</code>

----

===== Rimuovere servizio =====

<code bash>
# Fermare e disattivare
sudo systemctl stop data-gateway
sudo systemctl disable data-gateway

# Rimuovere file unit
sudo rm /etc/systemd/system/data-gateway.service
sudo systemctl daemon-reload

# Rimuovere file (opzionale)
sudo rm -rf /opt/data-gateway
sudo userdel datagateway
</code>

----

===== Runbook Correlati =====

  * [[.:docker|Docker]] - Alternativa container
  * [[..:monitoring:prometheus|Prometheus]] - Esportare metriche
  * [[..:sicherheit:tls-einrichten|Configurare TLS]] - HTTPS

----

<< [[.:windows-dienst|<- Servizio Windows]] | [[.:docker|-> Docker]] >>

----
//Wolfgang van der Stille @ EMSR DATA d.o.o. - Data Gateway Professional//

{{tag>operator runbook linux systemd service}}