Skip to content

Admin & TargetShot‑Connect

Überblick

TargetShot‑Connect verbindet den Schießstand mit der Cloud. Ohne Connect sind Login und Synchronisation nicht verfügbar.

Installation (Überblick)

  1. System vorbereiten (Docker/Compose oder Debian‑Service)
  2. TargetShot‑Connect installieren und mit dem Vereins‑Account verknüpfen
  3. Firewall/Netzwerk prüfen, Health‑Check überwachen

Betrieb

  • Backups & Updates einplanen
  • Status/Health prüfen (Kacheln „Cloud-Sync“, „DB“, „Connector“)
  • Supportkontakt: [email protected]

Container-Images & Release-Kanäle

  • Pushes auf main triggern den Workflow Build & publish ts-connect (Environment release). Er baut Multi-Arch-Images (amd64/arm64), signiert sie per Cosign und veröffentlicht sie als targetshot.azurecr.io/ts-connect:<VERSION> sowie :<CommitHash>. Anschließend wird derselbe Digest ohne Rebuild auf :beta umgelegt.
  • Promotions laufen über den manuellen Workflow Promote ts-connect image. Quelle kann beta, stable, lts, ein beliebiger Tag oder ein nackter Digest (sha256:...) sein; Ziel ist einer der Kanäle beta|stable|lts. Rollbacks sind identisch: erneut promoten, aber mit dem vorherigen Digest.
  • Kunden binden ausschließlich die Kanal-Tags ein, z. B. image: targetshot.azurecr.io/ts-connect:stable. Tools wie Watchtower aktualisieren automatisch, sobald ihr Kanal neu gesetzt wird (containrrr/watchtower --interval 900 --rolling-restart).
  • OIDC-Anmeldung nutzt das GitHub-Environment release; statische Registry-Passwörter werden nicht gespeichert.

System-Update & Auto-Update

Voraussetzungen, die die UI prüft

Die Update-Karte validiert automatisch:

  • git ist verfügbar (wird benötigt, um neue Releases zu laden).
  • docker & Docker Socket (/var/run/docker.sock) sind gemountet.
  • Das Workspace-Volume (/workspace) liegt als Bind-Mount vor.

Fehlt eine Voraussetzung, erscheint der Hinweis in „System-Update“. Ohne „grün“ startete der Runner früher gar nicht.

Statusanzeige & neues Update-Modal

  • Während kein Update läuft, bleiben Badge & Text im Zustand „Bereit“ / „Auf aktuellem Stand“.
  • Sobald ein Update startet (manuell oder automatisch) zeigt die UI nun einen Vollbild-Modal mit:
  • Lauftext/Aktionsbeschreibung (current_action aus dem Backend).
  • Animierter Fortschrittsleiste.
  • Live-Log (gleiche Zeilen wie früheres Log-Panel).
  • Der Modal lässt sich nicht schließen, bis das Backend wieder „idle“ meldet. Dadurch kann niemand mehr versehentlich abbrechen, während Docker Compose neu baut.
  • Bei Fehlern bleiben die letzten Log-Zeilen im Modal sichtbar; das Polling informiert über neue Versuche.

Manuelles Update starten

  1. Nach Updates suchen vergleicht die lokale ts-connect/VERSION mit dem org.opencontainers.image.version-Label des ACR-Tags (Standard TS_CONNECT_UI_IMAGE bzw. targetshot.azurecr.io/ts-connect:stable) und zeigt an, ob eine neuere Version verfügbar ist. Zusätzlich wird der Digest des stable-Kanals mit dem laufenden UI-Container verglichen, sodass auch Re-Promotions ohne neue Versionsnummer erkannt werden. Bei privaten Registrys müssen TS_CONNECT_ACR_USERNAME und TS_CONNECT_ACR_PASSWORD gesetzt sein, damit die UI für die Abfrage automatisch ein docker login bzw. einen Token-Flow durchführen kann.
  2. Bei „Update verfügbar“ den Button Update starten wählen.
  3. Admin-Passwort eingeben (Schutz gegen versehentliche Klicks).
  4. Update-Modal beobachten; nach erfolgreichem Lauf lädt die UI automatisch neu.
  5. Der Update-Runner führt git pull, docker compose pull und anschließend docker compose up -d aus. Builds aus dem lokalen ./ui-Verzeichnis finden nur statt, wenn TS_CONNECT_UPDATE_BUILD_LOCAL=true gesetzt ist.
  6. Private Registry: Stelle sicher, dass docker login targetshot.azurecr.io bereits ausgeführt wurde oder setze TS_CONNECT_ACR_USERNAME/TS_CONNECT_ACR_PASSWORD, damit der Runner den Login automatisch übernimmt. Nutze möglichst einen Docker Credential Helper, damit Tokens verschlüsselt gespeichert werden.

Docker Credential Helper / Registry-Login

  • Empfohlen: Verwende einen Credential Helper (docker-credential-pass, docker-credential-secretservice, osxkeychain, …) und führe einmalig docker login targetshot.azurecr.io -u <Benutzer> --password-stdin mit einem ACR-Token/Service-Prinzipal aus. Die Zugangsdaten landen verschlüsselt in ~/.docker/config.json.
  • Falls kein Helper verfügbar ist, können Installationen die Variablen TS_CONNECT_ACR_USERNAME und TS_CONNECT_ACR_PASSWORD in .env setzen. Der Update-Runner loggt dann vor docker compose pull automatisch beim Registry-Host (TS_CONNECT_ACR_REGISTRY, Standard targetshot.azurecr.io) ein.

Auto-Update konfigurieren

  • Toggle „Automatisch aktiv“: aktiviert den täglichen Lauf.
  • Dropdown „Auto-Update täglich um“: Stundenwert (UTC) – default stammt aus TS_CONNECT_AUTO_UPDATE_HOUR (1 = 01:00 Uhr).
  • „Nächster Lauf“ zeigt berechneten ISO-Timestamp, solange Toggle aktiv ist.
  • „Letzter Auto-Lauf“ übernimmt auto_update_last_run.
  • Speichern löst einen Passwort-Dialog aus und persistiert in data/update_state.json.
  • Solange der Runner aktiv ist, sperrt die UI Buttons & Formulare (disabled + Opacity).
  • Ein Watchdog setzt hängende Läufe nach TS_CONNECT_AUTO_UPDATE_STALE_SECONDS Sekunden automatisch auf „idle“ und protokolliert den Eingriff.

Troubleshooting & Logs

  • Läuft ein Update länger als erwartet, bleibt der Modal geöffnet und das Log zeigt den letzten Schritt (z. B. docker compose up).
  • Fehlertexte stammen aus dem Runner; zusätzliche Hinweise erscheinen im update_state.log.
  • Über „Health Summary“ lassen sich parallel DB/Kafka/Connector prüfen – die UI triggert das Polling weiter.

Einstellungen & Konfiguration

.env

  • Vorlage: ts-connect/.env.example.
  • Beim Deployment liegt die Datei direkt als .env neben compose.yml, damit Docker Compose Variablen ersetzen kann.
  • Empfohlen: Beispiel kopieren, sensible Werte setzen (cp .env.example .env) und nur die wirklich benötigten Werte überschreiben.

Wichtige Umgebungsvariablen

Variable Zweck Standard
TS_CONNECT_UI_ADMIN_PASSWORD Passwort für den Admin-Dialog im UI. change-me
UI_BIND_IP Bind-Adresse der UI (z. B. 0.0.0.0 für LAN). 0.0.0.0
TS_CONNECT_WORKSPACE Pfad im Container, aus dem Releases gelesen werden. /workspace
TS_CONNECT_WORKSPACE_HOST Host-Pfad, falls Compose außerhalb des Repo-Stamms liegt. leer
TS_CONNECT_BACKUP_DB, TS_CONNECT_BACKUP_USER, TS_CONNECT_BACKUP_PORT Steuerung der integrierten Backup-Postgres-Instanz. targetshot_backup, targetshot, 5432
TS_CONNECT_LICENSE_API_KEY, TS_CONNECT_LICENSE_VARIANT_PLAN_MAP, TS_CONNECT_LICENSE_INSTANCE_* Lemon-Squeezy-Validierung (Lizenzschlüssel, Plan-Mapping, Gerätename). siehe Beispiel
TS_CONNECT_GITHUB_REPO Erzwingt ein anderes Repository für Updates (z. B. Fork). automatisch aus laufendem Image
TS_CONNECT_UPDATE_IMAGE Überschreibt das Image für den Update-Runner. aktuelles UI-Image
TS_CONNECT_UPDATE_CONTAINER_PREFIX Prefix des temporären Runner-Containers. ts-connect-update
TS_CONNECT_DOCKER_SOCKET Pfad zum Docker-Socket, der in den Runner gemountet wird. /var/run/docker.sock
TS_CONNECT_UPDATE_CACHE_SECONDS Cache-Dauer für Release-Infos (UI force=1 ignoriert Cache). 3600
TS_CONNECT_AUTO_UPDATE_HOUR Default-Stunde für Auto-Update-Auswahl (0–23). 1
TS_CONNECT_AUTO_UPDATE_POLL_SECONDS Polling-Intervall des Hintergrund-Workers. 60
TS_CONNECT_AUTO_UPDATE_STALE_SECONDS Sekunden bis ein hängender Update-Lauf automatisch freigegeben wird. 14400
TS_CONNECT_AUTO_UPDATE_FORCE_RELEASE Erzwingt Release-Refresh bei Auto-Updates (true/false). true
TS_CONNECT_UPDATE_COMPOSE_ENV Name der optionalen Env-Datei, die beim Update explizit via --env-file geladen wird (Standard .env, Legacy compose.env). .env
TS_STREAMS_TARGET_PREFIX Namensraum für Kafka-Topics des Streams-Transformers. ts.sds-test
ELASTIC_AGENT_ENABLED Aktiviert den Elastic-Agent-Health-Check in der UI. false
ELASTIC_FLEET_* Enrollment & Tags für den Elastic-Agent (optional). leer
TS_CONNECT_UI_IMAGE Vorgabebild für den UI-Container (targetshot.azurecr.io/ts-connect:stable). targetshot.azurecr.io/ts-connect:stable
TS_CONNECT_UPDATE_CHECK_IMAGE Optional anderes Tag, dessen Manifest für die Update-Prüfung ausgewertet wird. gleich TS_CONNECT_UI_IMAGE
TS_CONNECT_UI_CONTAINER_NAME Container-Name, dessen Image-Digest für Update-Vergleiche gelesen wird. ts-connect-ui
TS_CONNECT_UPDATE_BUILD_LOCAL Erzwingt lokale Builds im Update-Runner statt docker compose pull. false
TS_CONNECT_ACR_REGISTRY Optionaler Registry-Host für den automatischen Login. targetshot.azurecr.io
TS_CONNECT_ACR_USERNAME Benutzername für docker login, falls kein globaler Login existiert. leer
TS_CONNECT_ACR_PASSWORD Passwort/Token für docker login, das ausschließlich vom Update-Runner verwendet wird. leer

Docker Compose startet den Elastic Agent nur, wenn das Profil elastic aktiv ist (COMPOSE_PROFILES=elastic oder docker compose --profile elastic up -d).

Hinweis: Weitere Variablen (z. B. für Kafka oder Secrets) befinden sich in den Dateien .env.example sowie docker-compose*.yml. Die UI zeigt für sensible Werte Platzhalter (********) und schreibt Änderungen in /app/data/config.db.