Dokumentation

Installations-Anleitung

Alles was Sie benötigen, um ServerCtrl in Betrieb zu nehmen – vom Backend bis zu den Agenten auf Ihren Servern.

⏱ ca. 15 Min. ✓ Keine Root-Rechte am Backend nötig Python 3.9+
⚡

Voraussetzungen

Was Sie vor der Installation benötigen

🖥 Backend-Server
  • ✓ Python 3.9 oder neuer
  • ✓ pip (Python Paketmanager)
  • ✓ Öffentlich erreichbar (Port 443 oder 8000)
  • ✓ Optional: TLS-Zertifikat (Let's Encrypt)
  • ✓ Linux-Server empfohlen (Raspberry Pi genügt)
🤖 Agenten-Server
  • ✓ Windows 10/11 oder Server 2016+
  • ✓ oder Linux (Debian, Ubuntu, RHEL, …)
  • ✓ oder macOS 12+ (Intel oder Apple Silicon)
  • ✓ oder Synology DSM 6/7
  • ✓ Ausgehende HTTPS/WSS-Verbindung erlaubt
  • ✓ Administrator-/Root-Rechte
ℹ️ Die Agenten bauen ausgehende Verbindungen zum Backend auf – Sie müssen am Backend-Server lediglich einen eingehenden Port (z. B. 443 oder 8000) freigeben.
🖥

Backend installieren

Das zentrale ServerCtrl-Backend einrichten

1

Dateien übertragen

Übertragen Sie den ServerCtrl-Ordner auf Ihren Backend-Server (z. B. per SFTP oder scp).

bash
$ scp -r serverctrl/ user@meinserver.de:/opt/serverctrl # Oder per Git, falls verfügbar: $ git clone https://... /opt/serverctrl
2

Abhängigkeiten installieren

Alle benötigten Python-Pakete werden über pip installiert.

bash
$ cd /opt/serverctrl $ python3 -m venv venv $ source venv/bin/activate $ pip install -r requirements.txt
3

Umgebungsvariablen konfigurieren

Erstellen Sie eine .env-Datei im Backend-Verzeichnis mit Ihren Einstellungen.

.env
# Sicherheit SECRET_KEY=IhrGeheimesPasswort123! ADMIN_USERNAME=admin ADMIN_PASSWORD=SicheresPasswort! # Agent-Token (für Agenten-Authentifizierung) AGENT_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... # E-Mail Alerts (optional) SMTP_HOST=smtp.example.de SMTP_PORT=587 SMTP_USER=alerts@example.de SMTP_PASS=SmtpPasswort ALERT_TO=admin@example.de
4

Backend starten

Starten Sie das Backend direkt oder richten Sie es als Systemd-Dienst ein, damit es nach einem Neustart automatisch startet.

Direktstart (Test)
$ uvicorn main:app --host 0.0.0.0 --port 8000
/etc/systemd/system/serverctrl.service
[Unit] Description=ServerCtrl Backend After=network.target [Service] User=serverctrl WorkingDirectory=/opt/serverctrl ExecStart=/opt/serverctrl/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 Restart=always [Install] WantedBy=multi-user.target
Dienst aktivieren
$ systemctl daemon-reload $ systemctl enable --now serverctrl $ systemctl status serverctrl
5

Zugang prüfen

Öffnen Sie im Browser http://IhrServer:8000 – die ServerCtrl-Login-Seite sollte erscheinen.

✅ Das Backend ist betriebsbereit. Jetzt können Sie die Agenten auf Ihren zu überwachenden Servern installieren.
🪟

Windows Agent

Installation auf Windows 10/11 oder Windows Server

ℹ️ Das Installations-Script muss als Administrator ausgeführt werden, damit der Windows-Dienst angelegt werden kann.
1

Agent-Dateien bereitstellen

Kopieren Sie den Ordner serverctrl-agent-windows auf den Ziel-Server, z. B. nach C:\ServerCtrl\.

Ordnerstruktur
C:\ServerCtrl\ ├── serverctrl-agent.exe ├── install-agent-windows.bat └── config.json (wird beim Install erstellt)
2

Installations-Script ausführen

Rechtsklick auf install-agent-windows.bat → Als Administrator ausführen. Das Script führt Sie durch die Konfiguration.

Interaktive Eingaben
ServerCtrl Windows Agent – Installation ======================================== Backend-URL [wss://serverctrl.example.de]: _ Server-ID [MeinServer01]: _ Agent-Token [eyJ...]: _ Hostname [WIN-SERVER-01]: _ TLS prüfen [true]: _ → Schreibe config.json... → Installiere Windows-Dienst... → Starte Dienst... ✓ ServerCtrl-Agent läuft als Windows-Dienst!
3

Status prüfen

Der Agent läuft nun als Windows-Dienst und startet automatisch mit dem System. Status prüfen über Dienste-Manager oder PowerShell:

PowerShell
PS> Get-Service "ServerCtrl-Agent" Status Name DisplayName ------ ---- ----------- Running ServerCtrl-Agent ServerCtrl Agent
⚠️ Für Dienst-Verwaltung, Log-Zugriff und Benutzer-Abfragen benötigt der Agent lokale Administrator-Rechte. Das Service-Konto kann unter Dienste-Eigenschaften → Anmelden geändert werden.
🐧

Linux Agent

Installation auf Debian, Ubuntu, RHEL, CentOS u. v. m.

1

Binary und Script übertragen

Kopieren Sie serverctrl-agent-linux und install-agent-linux.sh auf den Zielserver.

bash
$ scp serverctrl-agent-linux install-agent-linux.sh user@linux-server:/tmp/ $ ssh user@linux-server $ chmod +x /tmp/install-agent-linux.sh
2

Installations-Script ausführen

Führen Sie das Script als Root aus. Es liest eine vorhandene Konfiguration automatisch ein und zeigt bestehende Werte als Vorbelegung.

bash
$ sudo bash /tmp/install-agent-linux.sh ServerCtrl Linux Agent – Installation ====================================== Backend-URL [wss://serverctrl.example.de]: ↵ Server-ID []: Linux-Server-01 Agent-Token [eyJ...]: ↵ TLS prüfen [true]: ↵ → Kopiere Binary nach /opt/serverctrl-agent/... → Schreibe /opt/serverctrl-agent/config.json... → Erstelle systemd-Dienst... ✓ serverctrl-agent.service aktiv!
3

Dienst-Status prüfen

bash
$ systemctl status serverctrl-agent ● serverctrl-agent.service - ServerCtrl Agent Loaded: loaded (/etc/systemd/system/serverctrl-agent.service) Active: active (running) since ... $ journalctl -u serverctrl-agent -f
ℹ️ Das Script legt automatisch einen systemd-Dienst an, der beim Systemstart automatisch aktiviert wird (systemctl enable).
📦

Synology Agent

Installation auf Synology NAS (DSM 6 / DSM 7)

1

Architektur des NAS ermitteln

Der richtige Binary hängt von der CPU-Architektur Ihres NAS ab. Verbinden Sie sich per SSH und prüfen Sie die Architektur:

SSH auf dem NAS
$ uname -m x86_64 # → serverctrl-agent-synology-amd64 aarch64 # → serverctrl-agent-synology-arm64 armv7l # → serverctrl-agent-synology-armv7
2

Dateien übertragen

Kopieren Sie den passenden Binary und das Installations-Script auf das NAS (z. B. in den /volume1/).

Von einem anderen Rechner
$ scp serverctrl-agent-synology-amd64 \ install-agent-synology.sh \ admin@192.168.1.100:/volume1/homes/admin/
3

Installations-Script ausführen

SSH auf dem NAS (als root/sudo)
$ sudo bash install-agent-synology.sh Architektur erkannt: x86_64 → amd64 Backend-URL [wss://serverctrl.example.de]: ↵ Server-ID []: Synology-NAS-01 Agent-Token [eyJ...]: ↵ → Kopiere Binary nach /usr/local/bin/... → Erstelle /usr/local/etc/rc.d/S99serverctrl-agent.sh... ✓ Synology Agent gestartet!
4

Autostart prüfen

Das Script legt automatisch ein rc.d-Script an, das den Agenten bei jedem NAS-Start aktiviert.

bash
$ ls -la /usr/local/etc/rc.d/S99serverctrl-agent.sh $ ps aux | grep serverctrl
⚠️ Stellen Sie in DSM unter Systemsteuerung → Terminal & SNMP sicher, dass SSH aktiviert ist. Nach der Installation kann SSH wieder deaktiviert werden.
🍎

macOS Agent

Installation auf macOS 12+ (Intel & Apple Silicon)

ℹ️ Das Installations-Script muss als root ausgeführt werden (sudo bash install-agent-macos.sh), damit der LaunchDaemon angelegt werden kann.
1

Architektur ermitteln

Der richtige Binary hängt von der CPU-Architektur ab. Prüfen Sie diese im Terminal:

Terminal
$ uname -m x86_64 # → serverctrl-agent-macos-amd64 (Intel) arm64 # → serverctrl-agent-macos-arm64 (Apple Silicon)
2

Dateien bereitstellen

Legen Sie den passenden Binary und das Installations-Script in dasselbe Verzeichnis, z. B. in den Downloads-Ordner.

Ordnerstruktur
~/Downloads/serverctrl-macos/ ├── serverctrl-agent-macos-arm64 (oder -amd64) └── install-agent-macos.sh
3

Installations-Script ausführen

Das Script erkennt die Architektur automatisch, liest eine vorhandene Konfiguration ein und führt Sie interaktiv durch die Einrichtung.

Terminal
$ sudo bash install-agent-macos.sh ╔══════════════════════════════════════════════╗ ║ ServerCtrl – macOS Agent Installation ║ ╚══════════════════════════════════════════════╝ Architektur erkannt: arm64 → arm64 Backend-URL [wss://serverctrl.example.de]: ↵ Server-ID [MacBook-Pro]: Mac-Studio-01 Token [eyJ…]: ↵ Host [serverctrl.example.de]: ↵ Gruppe []: ↵ TLS prüfen? [J/n]: ↵ → Installiere Agent-Binary nach /Library/ServerCtrl/... → Schreibe /Library/ServerCtrl/config.json... → Richte LaunchDaemon ein... ✓ LaunchDaemon geladen und gestartet
4

Status prüfen & verwalten

Terminal
# Status prüfen $ launchctl print system/com.serverctrl.agent # Log ansehen $ tail -f /var/log/serverctrl-agent.log # Agent stoppen $ sudo launchctl bootout system/com.serverctrl.agent # Agent neu starten $ sudo launchctl bootstrap system /Library/LaunchDaemons/com.serverctrl.agent.plist
✅ Der macOS Agent startet automatisch beim Systemstart über den LaunchDaemon und verbindet sich mit dem Backend. Er erscheint sofort im Agent-Dashboard.
⚙

Konfiguration

Übersicht aller Agent-Konfigurationsparameter

Alle Agenten verwenden eine config.json die beim Installationsscript automatisch erstellt wird. Sie können sie jederzeit anpassen:

config.json
{ "backend_url": "wss://serverctrl.example.de", "server_id": "MeinServer-01", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "host": "MEIN-HOSTNAME", "verify_tls": true }
Parameter Beschreibung Beispiel
backend_url WebSocket-URL des ServerCtrl-Backends. wss:// für TLS, ws:// für unverschlüsselt (nur lokal). wss://serverctrl.example.de
server_id Eindeutige ID dieses Servers im Dashboard. Wird als Anzeigename verwendet. Web-Server-01
token JWT Bearer-Token zur Authentifizierung am Backend. Wird in der Backend-.env als AGENT_TOKEN gesetzt. eyJhbGci...
host Hostname oder IP-Adresse des Servers (für Anzeige im Dashboard). 192.168.1.100
verify_tls TLS-Zertifikat des Backends prüfen. false nur bei selbst-signierten Zertifikaten im internen Netz. true
❓

Häufige Fragen

Lösungen für typische Probleme

Der Agent verbindet sich nicht mit dem Backend.

Prüfen Sie: ① Ist die backend_url in der config.json korrekt? ② Ist Port 8000 (oder 443) am Backend-Server in der Firewall freigegeben? ③ Stimmt der token mit dem AGENT_TOKEN in der Backend-.env überein?

TLS-Fehler: certificate verify failed

Setzen Sie in der config.json "verify_tls": false wenn Sie ein selbst-signiertes Zertifikat verwenden. Für Produktivbetrieb empfehlen wir ein gültiges Let's Encrypt-Zertifikat.

Wie aktualisiere ich einen Agenten?

Ersetzen Sie die ausführbare Datei durch die neue Version und starten Sie den Dienst neu: systemctl restart serverctrl-agent (Linux) bzw. den Windows-Dienst neu starten. Die config.json bleibt erhalten.

Wie werden Alert-E-Mails konfiguriert?

Alert-E-Mails werden im Backend konfiguriert – entweder in der .env-Datei (SMTP-Einstellungen) oder direkt in der ServerCtrl-Web-Oberfläche unter Einstellungen → Benachrichtigungen.

Kann ich das Backend hinter einem Reverse-Proxy betreiben?

Ja. nginx oder Caddy eignen sich hervorragend. Wichtig: WebSocket-Upgrade muss durchgeleitet werden (proxy_set_header Upgrade $http_upgrade). Kontaktieren Sie uns für eine Beispiel-Konfiguration.

Weitere Fragen?

Kontakt aufnehmen →