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

<WRAP round info>
**Duration:** ~10 minutes \\
**Role:** Linux Administrator \\
**Prerequisite:** root/sudo, .NET 8 Runtime
</WRAP>

Run Data Gateway as systemd service on Linux.

----

===== Workflow =====

<mermaid>
flowchart TD
    A[Start] --> B[Install Gateway]
    B --> C[Create service unit]
    C --> D[systemctl enable]
    D --> E[systemctl start]
    E --> F[Health Check]
    F --> G{OK?}
    G -->|Yes| H[Done]
    G -->|No| I[Check journalctl]

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

----

===== 1. Install Gateway =====

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

# Copy files
cp -r ./publish/* /opt/data-gateway/

# Make executable
chmod +x /opt/data-gateway/WvdS.WebAPI.Data.Gateway.Api

# Adjust configuration
sudo nano /opt/data-gateway/appsettings.json
</code>

----

===== 2. Create User =====

<code bash>
# Dedicated service user
sudo useradd --system --no-create-home --shell /sbin/nologin datagateway

# Set permissions
sudo chown -R datagateway:datagateway /opt/data-gateway
</code>

----

===== 3. Create systemd Unit =====

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

**Content:**

<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

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

# Limits
LimitNOFILE=65536
TimeoutStopSec=30

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

----

===== 4. Enable Service =====

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

# Enable auto-start
sudo systemctl enable data-gateway

# Start service
sudo systemctl start data-gateway

# Check status
sudo systemctl status data-gateway
</code>

----

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

<code bash>
# Wait until ready
sleep 5

# Health Check
curl -s http://localhost:5000/health
# Expected response: "Healthy"

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

----

===== 6. Show Logs =====

<code bash>
# Recent logs
sudo journalctl -u data-gateway -n 50 --no-pager

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

# Since today
sudo journalctl -u data-gateway --since today

# Errors only
sudo journalctl -u data-gateway -p err
</code>

----

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

| # | Check | Done |
|---|-------|------|
| 1 | .NET 8 installed | [ ] |
| 2 | Gateway in /opt/data-gateway | [ ] |
| 3 | Service user created | [ ] |
| 4 | Unit file created | [ ] |
| 5 | Service enabled | [ ] |
| 6 | Service started | [ ] |
| 7 | Health Check OK | [ ] |

----

===== Service Commands =====

| Command | Description |
|---------|-------------|
| ''systemctl start data-gateway'' | Start |
| ''systemctl stop data-gateway'' | Stop |
| ''systemctl restart data-gateway'' | Restart |
| ''systemctl status data-gateway'' | Status |
| ''systemctl enable data-gateway'' | Auto-start on |
| ''systemctl disable data-gateway'' | Auto-start off |

----

===== Troubleshooting =====

| Problem | Cause | Solution |
|---------|-------|----------|
| ''code=exited, status=203'' | Wrong path | Check ExecStart |
| ''code=exited, status=1'' | Config error | Check journalctl |
| ''Permission denied'' | Wrong permissions | Check chown |
| ''Address already in use'' | Port in use | Different port or kill process |

**Detailed error analysis:**

<code bash>
# Test executable directly
sudo -u datagateway /opt/data-gateway/WvdS.WebAPI.Data.Gateway.Api

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

----

===== Change Port =====

In ''appsettings.json'':

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

**Open 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>

----

===== Remove Service =====

<code bash>
# Stop and disable
sudo systemctl stop data-gateway
sudo systemctl disable data-gateway

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

# Remove files (optional)
sudo rm -rf /opt/data-gateway
sudo userdel datagateway
</code>

----

===== Related Runbooks =====

  * [[.:docker|Docker]] - Container alternative
  * [[..:monitoring:prometheus|Prometheus]] - Export metrics
  * [[..:sicherheit:tls-einrichten|Set Up TLS]] - HTTPS

----

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

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

{{tag>operator runbook linux systemd service}}