CTmine-client/README.md

⛏ CTmine-client · ContainerMine Client

Eine Docker-WebApp, die einen echten Minecraft Java-Client im Container laufen lässt und ihn per noVNC direkt im Browser anzeigt. Ideal, um einen Account AFK an eine Farm zu stellen — ohne lokalen Minecraft-Client oder Java-Installation.

Das Dashboard ist eine Vite + Vue 3-Anwendung, die im selben Container mit ausgeliefert wird.

---

Architektur

Browser  ──HTTP/WS──▶  nginx (:8080)
                        ├── /            → Vue-Dashboard (statisch)
                        ├── /api/*       → Node-Status-API (127.0.0.1:3000)
                        └── /websockify  → websockify (127.0.0.1:6080)
                                              │
                       supervisord verwaltet ▼
                        Xvfb :0  →  x11vnc  →  websockify  →  Browser
                          ▲
                     Prism Launcher + echter Minecraft-Client
                     (rendert per Software-OpenGL/llvmpipe auf Xvfb)

Warum Prism Launcher statt offiziellem Mojang-Launcher? Der Mojang-Launcher nutzt für den Microsoft-Login ein eingebettetes Webview, das in einem headlessen Container regelmäßig Probleme macht. Prism startet denselben Vanilla-Client, ist aber container-freundlich und nutzt den Device-Code-Flow für den Login: Code notieren → microsoft.com/link auf irgendeinem Gerät öffnen → fertig.

---

Voraussetzungen

• Docker (mit BuildKit) und Docker Compose v2
• ~2 GB freier Speicher für das Image
• Einen gültigen Microsoft-Account mit Minecraft-Lizenz
• Chromium/Firefox (für WebGL & WebSocket in noVNC)

Lokales Bauen ohne Docker ist nicht vorgesehen. Wenn du nur das Dashboard entwickeln willst, siehe Entwicklung.

---

Schnellstart

# 1. Env-Datei erzeugen und anpassen
cp .env.example .env
#    PUID/PGID mit `id -u` / `id -g` setzen, damit ./config dir gehört.

# 2. Image bauen und starten
docker compose up -d --build

# 3. Dashboard öffnen
#    http://localhost:8080

---

Erster Login (einmalig)

1. Dashboard öffnen → http://localhost:8080
2. Auf „Instanz starten“ klicken. Prism Launcher öffnet sich im VNC-Fenster.
3. In Prism oben rechts: Konto → Konto hinzufügen → Microsoft.
4. Prism zeigt einen Code an. Auf irgendeinem Gerät https://microsoft.com/link öffnen, Code eingeben, mit Microsoft einloggen.
5. Zurück in Prism: im Hauptfenster die gewünschte Instanz wählen und auf „Spielen“ klicken. Prism lädt die passende Minecraft-Version + Java automatisch herunter.
6. Im Minecraft-Hauptmenü: Mehrspieler → Server hinzufügen → Adresse der Farm eingeben → Verbinden.

Ab jetzt ist der Account auf der Farm. Der Login liegt persistent in ./config/prism und bleibt auch nach docker compose down erhalten.

Tipp: Bevor du den Container Neustartest, kannst du in Minecraft über Optionen → Steuerelemente auch schon die korrekte Farm-Anbindung (z. B. eine Trade/Anti-AFK-Makro-Mod) konfigurieren — sie bleibt erhalten.

---

AFK-Farm-Setup

Die konkrete Einrichtung hängt von deiner Farm ab. Typische Schritte:

• Anti-AFK: periodisch springen/bewegen, damit der Server dich nicht kickt. Du kannst die Vanilla-Funktion (z. B. Wasserstrom, der dich ständig leicht bewegt) nutzen oder eine Client-Mod wie Mouse Tweaks / Inventory Profiles installieren. Mods legst du über Prism in die jeweilige Instanz.
• Auto-Reconnect: manche Server trennen nach Stunden. Nutze ggf. eine Reconnect-Mod.
• Fenster offen lassen: Solange das Dashboard geöffnet ist, siehst du den Client live. Du kannst den Tab schließen — Minecraft läuft im Container weiter. Nur der Container muss laufen.

---

Konfiguration (.env)

Variable	Standard	Bedeutung
PUID / PGID	1000	UID/GID des Container-Benutzers. Mit id -u/id -g deines Host-Users setzen, damit ./config dir gehört.
TZ	Europe/Berlin	Zeitzone des Containers.
DISPLAY_WIDTH	1280	Breite des virtuellen Displays (MC-Auflösung).
DISPLAY_HEIGHT	720	Höhe des virtuellen Displays.
DISPLAY_DEPTH	24	Farbtiefe (24 = 8-bit RGB).
DISPLAY_REFRESH	60	Bildwiederholrate des virtuellen Displays.
WEB_PORT	8080	Browser-Port.
VNC_PASSWORD	(leer)	Optional. Leer = ohne Auth (nur lokales Netz!).
X11VNC_EXTRA	siehe .env	Low-Latency-/Eingabe-Flags für x11vnc.

---

Steuerung über VNC

Die Steuerung ist auf Minecraft-Menü, Chat, Inventar und AFK-Farmen optimiert. Sie ist nicht für aktives PVP/Mouselook gedacht — das ist eine grundsätzliche Grenze von VNC (siehe unten).

Bedienung im Browser:

• Klick ins Bild → setzt den Tastaturfokus ins Spielfenster (Tasten gehen ans Spiel, nicht an den Browser).
• Maus freigeben → Strg + Alt + Umschalt (noVNC-Standard).
• Vollbild → Button in der Toolbar; für Minecraft flächendeckend.
• Zwischenablage → automatisch verknüpft (Login-Codes / Server-IPs kopieren geht direkt zwischen Browser und Container).

Was automatisch eingestellt ist:

• resize=remote: die Xvfb-Auflösung folgt der Fenstergröße (1:1-Maus-Mapung, keine Skalierungs-Unschärfe).
• reconnect=1: bei Abbruch verbindet noVNC selbstständig neu.
• x11vnc mit -threads -pointer_mode 4 -norepeat:
  • -threads → parallele I/O-Threads, weniger Eingabe-Lag.
  • -pointer_mode 4 → flüssigere Mausübertragung als der Default (1).
  • -norepeat → verhindert doppelte Tastaturwiederholungen im Spiel.
• -nodpms -nofbpm -nowf -nowcr → Energiesparen und Rate-Limiting aus, damit nichts nach Leerlauf ruckelt.

Für langsames Netz (z. B. Remote über Internet statt LAN) in der .env Kompression aktivieren:

X11VNC_EXTRA=-threads -pointer_mode 4 -norepeat -tight -compresslevel 6 -quality 7

Warum Mouselook nicht richtig geht

VNC überträgt absolute Mauskoordinaten („Cursor an Position X/Y"). Minecraft wie jedes FPS-artige Spiel braucht aber relative Mausbewegung und setzt den Cursor dafür jeden Frame auf die Bildmitte zurück (noVNC Issue #1493). Darum lässt sich die Kamera per VNC nicht sinnfrei drehen.

Für Menü, Buttons, Chat, Inventar und reines AFK auf einer Farm ist das ohne Bedeutung. Wer wirklich remote spielen will, braucht ein anderes Protokoll (Sunshine/Moonlight statt VNC) — das ist mit dieser Architektur nicht abgedeckt.

---

API

Methode	Pfad	Beschreibung
GET	/api/status	Status von Display, VNC und Minecraft.
POST	/api/mc/start	Startet Prism Launcher.
POST	/api/mc/stop	Beendet Prism + Minecraft.

Beispiel:

curl -X POST http://localhost:8080/api/mc/start

---

Dashboard entwickeln

Für die Vue-Entwicklung ohne jedes Mal neu zu bauen:

cd web
npm install
npm run dev    # → http://localhost:5173 (proxyt /api + /websockify nach :8080)

Damit das Dev-Dashboard funktioniert, muss der Container laufen (docker compose up -d), damit der VNC-Stream und die API erreichbar sind.

---

Performance-Hinweise

• Minecraft rendert im Container per llvmpipe (CPU-Software-OpenGL). Für AFK-Farmen absolut ausreichend (~1–2 CPU-Kerne), aber kein flüssiges PVP.
• shm_size: 1gb ist gesetzt, damit OpenGL genug Shared Memory hat.
• Bei verfübarer GPU kannst du /dev/dri durchreichen (in docker-compose.yml auskommentiert). MC nutzt dann Hardware-Rendering.

---

Projektstruktur

CTmine-client/
├── Dockerfile                # Multi-Stage: Vue-Build + Runtime
├── docker-compose.yml
├── .env.example
├── docker/
│   ├── entrypoint.sh         # PUID/PGID, /config, Xvfb/x11vnc-Conf generieren
│   ├── supervisor.conf       # Prozess-Manager für alle Dienste
│   ├── nginx.conf            # Dashboard + /api + /websockify Proxy
│   └── mc-api/               # Node-Status-API (ohne externe Dependencies)
│       ├── server.js
│       └── package.json
└── web/                      # Vite + Vue 3 + TypeScript Dashboard
    ├── package.json · vite.config.ts · tsconfig.json
    └── src/
        ├── App.vue · main.ts · api.ts · types.ts
        ├── styles/main.css
        └── components/
            ├── VncViewer.vue     # noVNC-Integration
            ├── ControlPanel.vue  # MC Start/Stop, Schnellstart-Anleitung
            └── StatusBar.vue     # Status-Indikatoren

---

Bekannte Einschränkungen

• Sound ist im MVP nicht konfiguriert (für AFK-Farmen irrelevant).
• Erster Login interaktiv: der Microsoft-Login muss einmalig im VNC-Fenster per Device-Code durchgeführt werden. Danach persistent.
• EULA/Nutzungsbedingungen: Dieses Projekt stellt nur die Infrastruktur bereit. Du bist selbst für die Einhaltung der Mojang/Minecraft-Nutzungs- bedingungen und der Regeln deines Zielservers verantwortlich.

---

Lizenz

MIT — siehe LICENSE falls beigefügt. Minecraft ist Eigentum von Mojang/Microsoft; dieses Projekt steht nicht in offizieller Verbindung.