Probleme mit Pi-Node hier meine empfohlene Lösung. Pi-Node unter Linux Docker, Installation/Migration, hier liegen die Probleme, so geht es!

Die Pi-Node unter Linux mit Docker zu betreiben klingt im ersten Moment simpel: Container starten, Ports freigeben, fertig. In der Praxis zeigt sich jedoch schnell, dass die Pi-Node intern deutlich komplexer aufgebaut ist als ein gewöhnlicher Docker-Service.

Der folgende Beitrag basiert auf einer realen Migration und Fehlersuche einer produktiven Pi Mainnet Node, die zuvor über ein Jahr stabil unter Windows mit Docker Desktop und WSL2 gelaufen ist und anschließend vollständig auf Linux migriert wurde.

---

Hinweise zu Datensicherung

Bei der Bearbeitung von Speichermedien: Festplatte, Virtuellen Festplatte, USB Stick, Volumen usw. sowie Datenbanken kann es zur Datenverlust kommen, was mehrere Ursachen haben kann. Eine Haftung ist generell ausgeschlossen.

Wenn Du die, die in diesem Beitrag, behandelten Themen und Beispielen folgst und diese Verwendest, empfehle ich dir ausdrücklich, fertige vorher eine Datensicherung an!

---

Dabei geht es nicht nur um die reine Installation, sondern vor allem um:

• typische Fehlerbilder
• PostgreSQL- und Rechteprobleme
• Unterschiede zwischen Windows/WSL und Linux
• Docker-spezifische Stolperfallen
• Netzwerkprobleme
• Monitoring
• sowie die zuverlässigste Methode zur Aktivierung der Pi-Node

Der Beitrag ist bewusst ausführlich gehalten und soll nicht nur eine „funktioniert irgendwie“-Lösung liefern, sondern den technischen Hintergrund verständlich machen.

Ausgangslage

Die ursprüngliche Umgebung bestand aus:

• Docker Desktop für Windows
• WSL2
• offizieller Pi Node Windows Software
• Docker Pi-Node Container

Die Node lief über ein Jahr stabil im Mainnet.

Danach begann ein schleichender Fehler:

• zunächst war alle paar Tage ein Neustart nötig
• dann täglich
• später blieb die Node dauerhaft hängen
• schließlich synchronisierte sie gar nicht mehr

Das typische Verhalten:

• Node bleibt bei Block 1 stehen
• keine sichtbare Aktivität
• Container läuft scheinbar normal
• keine Fehlermeldungen in der GUI

---

Probleme unter Windows und WSL2

Der erste Verdacht lag zunächst auf:

• Netzwerkproblemen
• beschädigten Chain-Daten
• fehlerhaften Buckets
• Docker-Problemen

Der Container selbst lief jedoch stabil:

docker ps -a

Die wichtigen Prozesse waren aktiv:

supervisorctl status

Ergebnis:

• postgresql RUNNING
• stellar-core RUNNING

Das sah zunächst korrekt aus.

Der entscheidende Hinweis zeigte sich jedoch später in den internen Verzeichnissen.

---

Das eigentliche Problem: PostgreSQL und Rechte

Die ersten klaren Hinweise ergaben sich aus den internen Datenpfaden.

Der entscheidende Punkt:

Die Node zeigte in der LOG:

Waiting for postgres to be available...

Der Container startete zwar PostgreSQL-Prozesse, die Datenbank selbst war aber nicht korrekt initialisiert.

Docker PostgreSQL die Falle, unter Docker Desktop und WSL

---

Das große Problem unter Windows + WSL2

Hier zeigte sich eine bekannte Docker-/WSL-Problematik.

Die Pi-Node speichert intern PostgreSQL-Daten in Docker Volumes bzw. Bind-Mounts. Unter Windows + WSL2 entstehen dabei häufig:

• UID/GID-Probleme
• Dateisperren
• inkonsistente Rechte
• WAL-/SHM-Locks
• beschädigte PostgreSQL-Dateien

Genau dieses Verhalten trat auch hier auf.

Typische Symptome:

Permission denied

beim Löschen oder Schreiben.

Besonders kritisch:

• DIPS
• DIPS-shm
• DIPS-wal
• LevelDB Dateien
• PostgreSQL WAL Dateien

---

Warum die Probleme schleichend schlimmer wurden

Das Verhalten entwickelte sich nicht zufällig langsam.

Sehr wahrscheinlich entstanden:

• inkonsistente Schreibvorgänge
• beschädigte WAL-Dateien
• Dateisperren durch WSL
• zunehmende PostgreSQL-Instabilität

Dadurch musste die Node:

• zuerst selten
• später immer häufiger
• schließlich dauerhaft

neu gestartet werden.

Das erklärt auch das typische Verhalten:

Block 1 und keine weitere Aktivität

---

Migration auf Linux Docker

Nach den Problemen unter Windows erfolgte die vollständige Migration auf Linux.

Das Ziel:

• kein Docker Desktop
• kein WSL2
• native Linux Docker Umgebung

Die neue Umgebung:

• Ubuntu Linux
• Docker Engine
• Docker Compose
• native Volumes

---

Docker Compose Setup

Die Pi-Node wurde bewusst minimal aufgebaut.

services:
  pi-node:
    image: pinetwork/pi-node-docker:community-v1.0-p22.1
    container_name: pi-node
    restart: always
    command: ["--mainnet"]

    ports:
      - "31400-31409:31400-31409"
      - "11626:11626"

    volumes:
      - ./pi-node-data:/opt/data

Wichtig:

Die Verwendung eines nativen Linux-Dateisystems verbessert Stabilität und Performance erheblich gegenüber WSL-Bind-Mounts.

---

Welche Pi-Node Version ist aktuell sinnvoll?

Zum Zeitpunkt der Migration war:

pinetwork/pi-node-docker:community-v1.0-p22.1

die stabilste und sinnvollste Wahl.

Neuere Images wie:

community-v1.0-p23.0.1

existieren bereits, enthalten jedoch größere interne Migrationen.

Für produktive Nodes empfiehlt sich zunächst:

• p22.1 stabil betreiben
• p23 später kontrolliert testen

---

Aktivierung und Registrierung der Pi-Node

Die wichtigste Erkenntnis:

Die Pi-Node ist technisch nicht wirklich an Windows gebunden.

Allerdings erfolgt die offizielle Registrierung derzeit weiterhin am zuverlässigsten über die Windows Pi Node Desktop App.

---

Zuverlässigste Aktivierungsstrategie

Empfohlener Ablauf:

1. Einmalige Registrierung unter Windows

Voraussetzung für die Aktivierung der Node:

• installierte Pi Network Handy App
• verifizierter Pi Account
• installierte Windows Pi Node Software

Download der offiziellen Pi Node Software:

node

Die Windows Pi Node Software muss installiert und einmal vollständig eingerichtet werden.

Dabei erfolgt:

• Anmeldung mit dem Pi Account
• Verknüpfung mit der Handy App
• Erzeugung der Node-ID
• Erzeugung des NODE_SEED
• Verifizierung der Ports
• Aktivierung der Node
• Pi Node Desktop installieren
• Node aktivieren
• Ports testen
• Verifizierung abschließen

Dadurch werden erzeugt:

• NODE_SEED
• Node Public Key
• vollständige stellar-core.cfg

---

2. Danach Migration auf Linux

Unter Linux werden anschließend übernommen:

• stellar-core.cfg
• Volumes
• Node-ID
• NODE_SEED

Danach kann die Node vollständig ohne Windows betrieben werden.

Wo finde ich die Dateien unter Windows?

Die relevanten Dateien befinden sich typischerweise unter:

C:\Users\<BENUTZER>\AppData\Roaming\Pi Network\

Wichtige Dateien und Ordner:

stellar-core.cfg

sowie die Docker-Daten bzw. Volumes der Node.

Je nach Installation befinden sich die eigentlichen Daten zusätzlich unter:

C:\Users\<BENUTZER>\AppData\Roaming\Pi Network\docker_volumes\

Dort liegen unter anderem:

• buckets
• PostgreSQL Daten
• Ledger Daten
• History Daten

---

Wohin unter Linux kopieren?

Im Linux Docker Setup werden die Daten typischerweise nach:

/opt/data

bzw. in den gemounteten Docker-Volume-Ordner kopiert.

Im hier verwendeten Docker-Compose Beispiel:

volumes:
  - ./pi-node-data:/opt/data

liegt der tatsächliche Datenordner auf dem Linux Host unter:

./pi-node-data

Dort befinden sich anschließend unter anderem:

• PostgreSQL Daten
• buckets
• stellar-core Konfiguration
• Node Daten

Die stellar-core.cfg gehört im Container typischerweise nach:

/opt/stellar/core/etc/stellar-core.cfg

---

Warum das sinnvoll ist

Die Windows-App übernimmt intern:

• Registrierung
• Key-Erzeugung
• API-Initialisierung
• Verknüpfung mit der Pi-App

Diese Prozesse sind unter reinem Linux derzeit kaum dokumentiert.

---

Finale funktionierende stellar-core.cfg

Die entscheidenden Punkte:

PUBLIC_HTTP_PORT = true
HTTP_PORT = 11626
PEER_PORT = 31402

Wichtig:

# HTTP_LOCAL_ONLY = false

nicht aktiv setzen.

---

Starten der Pi-Node

Zeit unsere Pi-Node unter Linux zu starten:

docker compose up -d

Lasse jetzt die Pi-Node erst mal 15 Minuten in ruhe, initiieren !

---

Überprüfung der Synchronisation

Der wichtigste Test:

curl http://127.0.0.1:11626/info

Wichtige Werte:

"state": "Synced!"

"ledger"

"authenticated_count"

Damit lässt sich direkt prüfen:

• Node online
• Ledger aktuell
• Peers verbunden
• Synchronisation aktiv

---

Wichtige Erkenntnisse aus der Migration

1. WSL2 ist kritisch für PostgreSQL

Besonders problematisch:

• WAL-Dateien
• Dateisperren
• Rechteverwaltung

---

2. Native Linux Docker Umgebungen sind deutlich stabiler

Weniger:

• Rechteprobleme
• File Locks
• I/O Probleme

---

3. Die Pi-Node ist intern komplexer als normale Container

Die Node enthält:

• PostgreSQL
• Stellar Core
• Supervisor
• interne Migrationen
• History Buckets

---

4. Viele Fehler wirken wie Netzwerkprobleme, sind aber Dateisystemprobleme

Typische Symptome:

• Block 1
• kein Sync
• keine API
• zufällige Neustarts

sind häufig:

• beschädigte Datenbanken
• Rechteprobleme
• inkonsistente Volumes

---

Monitoring mit Uptime Kuma

Die Node war intern synchronisiert:

curl http://127.0.0.1:11626/info

Ergebnis:

"state" : "Synced!"

Trotzdem blieb Uptime Kuma dauerhaft rot.

Die Ursache lag letztlich in genau einer einzigen Zeile:

HTTP_LOCAL_ONLY = false

Nach dem Auskommentieren:

# HTTP_LOCAL_ONLY = false

war die API plötzlich korrekt erreichbar.

Das Verhalten zeigt:

Die Pi-Node reagiert teilweise empfindlich auf bestimmte explizite Flags, obwohl deren gesetzter Wert eigentlich logisch erscheinen würde.

---

Detailliertes Anlegen des Monitors in Uptime Kuma

In neueren Uptime Kuma Versionen genügt ein einfacher HTTP-Monitor.

Monitor hinzufügen

In Uptime Kuma:

Add New Monitor

---

Einstellungen

Monitor Type

HTTP(s) - Suchwortwort

---

Friendly Name

Pi Node Sync

---

URL

http://127.0.0.1:11626/info

Falls Uptime Kuma in einem separaten Container läuft, stattdessen die lokale IP des Docker Hosts verwenden:

http://192.168.x.x:11626/info

---

Suchwort

Syncet!

---

Dadurch prüft Kuma, ob der Text:

"state" : "Synced!"

in der API Antwort enthalten ist.

---

Wichtig

Damit der Monitor funktioniert, muss die Node API erreichbar sein.

Entscheidend war hier:

# HTTP_LOCAL_ONLY = false

und zusätzlich:

PUBLIC_HTTP_PORT = true
HTTP_PORT = 11626

sowie das Docker Port-Mapping:

- "11626:11626"

Erst danach konnte Uptime Kuma den Sync-Status korrekt abrufen.

---

Warum Uptime Kuma nur begrenzt sinnvoll ist

Uptime Kuma eignet sich gut für:

• HTTP-Erreichbarkeit
• Port-Checks
• einfache Statusanzeigen

Für Blockchain Nodes fehlen jedoch:

• Ledger-Lag
• Peer-Qualität
• Sync-Status
• Catchup-Fortschritt
• Quorum-Analyse

Dadurch wirkt Kuma häufig „rot“, obwohl die Node technisch korrekt arbeitet.

---

Fazit

Die Pi-Node unter Linux Docker zu betreiben ist absolut möglich und langfristig die stabilere Lösung gegenüber Windows + WSL2.

Allerdings zeigt die Praxis:

Die Pi-Node verhält sich intern eher wie ein gekapseltes verteiltes System als wie ein einfacher Docker-Container.

Die wichtigsten Erfolgsfaktoren sind:

• native Linux-Dateisysteme
• stabile Docker Volumes
• saubere PostgreSQL-Daten
• funktionierende HTTP-Konfiguration
• vorsichtige Updates
• und eine einmalige Aktivierung über die offizielle Windows-App

Hat man diese Punkte sauber umgesetzt, läuft die Node stabil, performant und deutlich wartbarer als unter WSL2.

Gerade die Kombination aus nativen Linux-Dateisystemen, Docker Compose und einer sauberen Trennung von Node, Datenbank und Monitoring sorgt langfristig für deutlich mehr Stabilität als klassische WSL2-Installationen unter Windows.

Wer die Node produktiv und dauerhaft betreiben möchte, sollte deshalb möglichst früh auf eine native Linux Docker Umgebung wechseln.

---

---

#PiNode #Docker #Linux #PiNetwork #Blockchain #SelfHosting #Crypto #StellarCore