Files

Alexander Zielonka 1db72ce92f Fix CLAUDE.md: repo holds GSM app code, deploy is via Gitea Actions

- Repository Purpose: it's not docs-only — the repo holds the GSM app
  (gsm-backend/, gsm-frontend/) plus docs/.
- Deployment: corrected "GitHub" to the actual Gitea remote
  (git.zeasy.dev) and Gitea Actions pipeline (.gitea/workflows/deploy.yml),
  which builds the frontend and copies to the server itself.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-26 19:39:58 +02:00

4.7 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Purpose

This repository holds the Gameserver Monitor (GSM) web application together with the homelab documentation:

gsm-backend/ — Node.js + Express API (the GSM server)
gsm-frontend/ — React + Vite + TailwindCSS frontend
docs/ — technical documentation for the homelab servers, services, and network configuration

The deployed app runs at /opt/gameserver-monitor/ on the monitor LXC (192.168.2.30).

Infrastructure Overview

The homelab consists of:

Raspberry Pi (192.168.2.10): Runs Nginx Proxy Manager, Cloudflare DDNS, and Nextcloud via Docker
Proxmox Server (192.168.2.20): Virtualization host running LXC containers and VMs
Gameserver Monitor (192.168.2.30): React/Node.js webapp for monitoring game servers (LXC)
Factorio Server (192.168.2.50): Docker-based game server (LXC)
Minecraft Server (192.168.2.51): FTB StoneBlock 4 modded server (MC 1.21.1 / NeoForge) running via screen (VM)
V Rising Server (192.168.2.52): Dedicated server (LXC)
Palworld Server (192.168.2.53): Dedicated server with systemd (LXC)
Project Zomboid Server (10.0.30.66): Dedicated server (external VM)
Terraria Server (10.0.30.202): tModLoader mit Calamity Mod, PM2 (external VM, VPN)
Hytale Server (10.0.30.204): Dedicated server mit tmux (external VM, VPN)

Key Technical Details

Gameserver Monitor Stack: React + Vite + TailwindCSS frontend, Node.js + Express backend, SQLite for auth, nginx as reverse proxy. Located at /opt/gameserver-monitor/ on the monitor LXC.

Gameserver Monitor Rollensystem:

user: Kann nur Server-Metriken sehen (CPU, RAM, Players, Uptime)
moderator: Zusätzlich Konsole, RCON, Server Start/Stop/Restart, Auto-Shutdown, Config-Editoren
superadmin: Zusätzlich Nutzerverwaltung, Activity Log, Anzeigeeinstellungen (Verbindungsadresse/Hinweis pro Server)

GSM Features:

Dashboard mit Server-Karten (Status, Metriken, Spieleranzahl)
Server-Detailansicht mit Tabs (Übersicht, Metriken, Konsole, Einstellungen, etc.)
Auto-Shutdown: Server stoppt automatisch wenn keine Spieler online sind
Config-Editoren: Palworld (INI), Project Zomboid (INI/Lua)
Factorio Weltverwaltung: Spielstände erstellen/löschen/laden
Minecraft Whitelist-Verwaltung via RCON
Anzeigeeinstellungen: Superadmins können Verbindungsadresse und Hinweis pro Server anpassen
Activity Log: Protokolliert alle Aktionen mit Discord-Avatar

Domain: zeasy.dev with subdomains managed via Cloudflare DDNS (gsm.zeasy.dev, factorio.zeasy.dev, palworld.zeasy.dev, pz.zeasy.dev, hytale.zeasy.dev)

SSH Access: Zugriff auf Server erfolgt über den Pi als Jump-Host:

ssh alex@192.168.2.10  # Erst auf den Pi
ssh root@192.168.2.XX  # Dann zum Zielserver (z.B. .53 für Palworld)

Oder in einem Befehl: ssh alex@192.168.2.10 "ssh root@192.168.2.53 'befehl'"

GSM API - Wichtige interne Routes

Discord Update senden (nur von localhost):

ssh root@192.168.2.30 'curl -X POST http://localhost:3000/api/servers/discord/internal-update \
  -H "Content-Type: application/json" \
  -d "{\"title\": \"Titel\", \"description\": \"Beschreibung\", \"serverType\": \"hytale\", \"color\": 65535}"'

serverType: minecraft, factorio, zomboid, vrising, palworld, terraria, openttd, hytale (für Icon)
color: Dezimal-Farbwert (z.B. 0x00BFFF = 49151)

Server ohne RCON (Spielererkennung via Log-Parsing):

Hytale: Spieler werden über Server-Logs erkannt ([World|*] Player joined / [PlayerSystems] Removing player)
Terraria: Spieler werden über PM2-Logs erkannt (ist beigetreten / ist weg)
Bei neuen Servern ohne RCON: server.type === 'serverid' zu folgenden Dateien hinzufügen:
- services/autoshutdown.js (Zeile ~50)
- services/discordBot.js (fetchServerStatuses, Zeile ~379)
- routes/servers.js (zwei Stellen, suche nach rconPassword || server.type)

Deployment

Deployt wird über Gitea Actions (.gitea/workflows/deploy.yml); Remote ist origin = https://git.zeasy.dev/ZeasyAlex/GSM.git.

WICHTIG: NIEMALS manuell per SCP/rsync deployen! Alle Änderungen am GSM-Code müssen:

Lokal committed werden
Auf den main-Branch (Gitea-Remote origin) gepusht werden
Die Pipeline baut das Frontend (npm run build) und deployt Backend + dist/ automatisch auf den Monitor (192.168.2.30), danach pm2 restart gsm-backend

Der Deploy triggert nur bei Änderungen unter gsm-backend/** oder gsm-frontend/**. Das Kopieren auf den Server übernimmt ausschließlich die Pipeline (per scp-action) — kein manuelles SCP/rsync.

Language Note

Documentation is written in German.

4.7 KiB Raw Blame History