You are currently viewing Pi-Node on Linux Docker, Installation/Migration

Pi-Node on Linux Docker, Installation/Migration

Having trouble with Pi-Node? Here’s my recommended solution. Pi-Node on Linux Docker: installation and migration—here are the issues, and here’s how to fix them!

Running a Pi-Node on Linux with Docker sounds simple at first glance: start containers, expose ports, done. In practice, however, it quickly becomes apparent that the Pi-Node is internally far more complex than a typical Docker service.

The following article is based on a real migration and troubleshooting process of a productive Pi Mainnet Node that had previously been running stably for over a year on Windows with Docker Desktop and WSL2 before being fully migrated to Linux.

Notes on data backup

When processing storage media: hard disk, virtual hard disk, USB stick, volume etc. and databases, data may be lost for several reasons. Liability is generally excluded.

If you follow the topics and examples discussed in this article and use them, I strongly recommend that you make a data backup beforehand!

This is not only about the installation itself, but especially about:

  • typical failure scenarios
  • PostgreSQL and permission issues
  • differences between Windows/WSL and Linux
  • Docker-specific pitfalls
  • networking problems
  • monitoring
  • and the most reliable method for activating the Pi-Node

The article is intentionally detailed and is meant not only to provide a “works somehow” solution, but also to explain the technical background.

Video: Pi-Node on Linux Docker, Installation/Migration

Language: 🇩🇪|🇬🇧
☝️ Use YouTube subtitles for all languages.

Initial Situation

The original environment consisted of:

  • Docker Desktop for Windows
  • WSL2
  • official Pi Node Windows software
  • Docker Pi-Node container

The node had been running stably on Mainnet for over a year.

Then a gradual failure started to appear:

  • at first, a restart was needed every few days
  • then daily
  • later, the node became permanently stuck
  • eventually, it stopped synchronizing completely

Typical behavior:

  • node remains at block 1
  • no visible activity
  • container appears to run normally
  • no error messages in the GUI

Problems under Windows and WSL2

The first suspicion initially focused on:

  • networking issues
  • corrupted chain data
  • damaged buckets
  • Docker problems

However, the container itself was running stably:

docker ps -a

The important processes were active:

supervisorctl status

Result:

  • postgresql RUNNING
  • stellar-core RUNNING

At first glance, this looked correct.

The decisive clue appeared later inside the internal directories.

The Actual Problem: PostgreSQL and Permissions

The first clear indications came from the internal data paths.

The critical point:

The Node showed in the LOG:

Waiting for postgres to be available...

The container did start PostgreSQL processes, but the database itself was no longer initialized correctly.

Docker PostgreSQL the Trap, under Docker Desktop and WSL

The Major Problem under Windows + WSL2

This exposed a well-known Docker/WSL issue.

Internally, the Pi-Node stores PostgreSQL data inside Docker volumes or bind mounts. Under Windows + WSL2 this frequently leads to:

  • UID/GID problems
  • file locks
  • inconsistent permissions
  • WAL/SHM locks
  • corrupted PostgreSQL files

Exactly this behavior occurred here.

Typical symptoms:

Permission denied

when deleting or writing files.

Especially critical:

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

Why the Problems Gradually Became Worse

The behavior did not slowly degrade by coincidence.

Most likely the following occurred:

  • inconsistent write operations
  • corrupted WAL files
  • file locks caused by WSL
  • increasing PostgreSQL instability

As a result, the node had to be restarted:

  • rarely at first
  • later more frequently
  • eventually permanently

This also explains the classic behavior:

Block 1 and no further activity

Migration to Linux Docker

After the problems under Windows, the node was fully migrated to Linux.

The goal:

  • no Docker Desktop
  • no WSL2
  • native Linux Docker environment

The new environment:

  • Ubuntu Linux
  • Docker Engine
  • Docker Compose
  • native volumes

Docker Compose Setup

The Pi-Node was intentionally built with a minimal setup.

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

Important:

Using a native Linux filesystem significantly improves stability and performance compared to WSL bind mounts.

Which Pi-Node Version Currently Makes Sense?

At the time of the migration:

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

was the most stable and practical choice.

Newer images such as:

community-v1.0-p23.0.1

already exist, but contain larger internal migrations.

For productive nodes it is recommended to:

  • run p22.1 stably first
  • test p23 later in a controlled way

Activation and Registration of the Pi-Node

The most important insight:

Technically, the Pi-Node is not really tied to Windows.

However, official registration is currently still performed most reliably through the Windows Pi Node Desktop App.

Most Reliable Activation Strategy

Recommended procedure:

1. One-Time Registration under Windows

Requirements for activating the node:

  • installed Pi Network mobile app
  • verified Pi account
  • installed Windows Pi Node software

Download the official Pi Node software:

Pi Node Official Website

The Windows Pi Node software must be installed and fully configured once.

During this process:

  • login with the Pi account
  • linking with the mobile app
  • generation of the Node-ID
  • generation of the NODE_SEED
  • port verification
  • node activation
  • install Pi Node Desktop
  • activate node
  • test ports
  • complete verification

This generates:

  • NODE_SEED
  • Node Public Key
  • complete stellar-core.cfg

2. Then Migration to Linux

Under Linux the following are then transferred:

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

After that, the node can run completely without Windows.

Where are the files located under Windows?

The relevant files are typically located at:

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

Important files and folders:

stellar-core.cfg

as well as the Docker data or node volumes.

Depending on the installation, the actual data may additionally be located under:

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

This includes:

  • buckets
  • PostgreSQL data
  • ledger data
  • history data

Where to copy them under Linux?

In a Linux Docker setup, the data is typically copied to:

/opt/data

or into the mounted Docker volume directory.

In the Docker Compose example used here:

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

the actual data directory on the Linux host is:

./pi-node-data

This then contains:

  • PostgreSQL data
  • buckets
  • stellar-core configuration
  • node data

The stellar-core.cfg typically belongs inside the container at:

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

Why This Makes Sense

Internally, the Windows app handles:

  • registration
  • key generation
  • API initialization
  • linking with the Pi app

These processes are currently barely documented for pure Linux environments.

Final Working stellar-core.cfg

The critical settings:

PUBLIC_HTTP_PORT = true
HTTP_PORT = 11626
PEER_PORT = 31402

Important:

# HTTP_LOCAL_ONLY = false

do not set this explicitly.

Starting the Pi-Node

Time to start our Pi-Node on Linux:

docker compose up -d

Leave the Pi node alone for 15 minutes first, then start it up!

Verifying Synchronization

The most important test:

curl http://127.0.0.1:11626/info

Important values:

"state": "Synced!"
"ledger"
"authenticated_count"

This directly verifies:

  • node online
  • ledger current
  • peers connected
  • synchronization active

Important Insights from the Migration

1. WSL2 is Critical for PostgreSQL

Especially problematic:

  • WAL files
  • file locks
  • permission management

2. Native Linux Docker Environments are Significantly More Stable

Fewer:

  • permission problems
  • file locks
  • I/O issues

3. The Pi-Node is Internally More Complex than Normal Containers

The node contains:

  • PostgreSQL
  • Stellar Core
  • Supervisor
  • internal migrations
  • history buckets

4. Many Errors Look Like Network Problems but are Actually Filesystem Problems

Typical symptoms:

  • block 1
  • no sync
  • no API
  • random restarts

are often caused by:

  • corrupted databases
  • permission issues
  • inconsistent volumes

Monitoring with Uptime Kuma

Internally, the node was synchronized:

curl http://127.0.0.1:11626/info

Result:

"state" : "Synced!"

Nevertheless, Uptime Kuma remained permanently red.

The cause ultimately came down to exactly one single line:

HTTP_LOCAL_ONLY = false

After commenting it out:

# HTTP_LOCAL_ONLY = false

the API suddenly became reachable correctly.

This behavior shows:

The Pi-Node reacts sensitively to certain explicit flags, even if their configured value would logically appear correct.

Detailed Creation of the Monitor in Uptime Kuma

In newer Uptime Kuma versions, a simple HTTP monitor is sufficient.

Add Monitor

In Uptime Kuma:

Add New Monitor

Settings

Monitor Type

HTTP(s) - Search term

Friendly Name

Pi Node Sync

URL

http://127.0.0.1:11626/info

If Uptime Kuma runs inside a separate container, use the local Docker host IP instead:

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

Keyword

Syncet!

Keyword

This allows Kuma to verify whether the text:

"state" : "Synced!"

Important

For the monitor to work, the node API must be reachable.

The decisive settings were:

# HTTP_LOCAL_ONLY = false

and additionally:

PUBLIC_HTTP_PORT = true
HTTP_PORT = 11626

as well as the Docker port mapping:

- "11626:11626"

Only after that could Uptime Kuma correctly retrieve the synchronization status.

Why Uptime Kuma is Only Partially Useful

Uptime Kuma works well for:

  • HTTP reachability
  • port checks
  • simple status displays

However, for blockchain nodes it lacks:

  • ledger lag
  • peer quality
  • sync status
  • catchup progress
  • quorum analysis

As a result, Kuma often appears “red” even though the node is technically functioning correctly.

Conclusion

Running a Pi-Node on Linux Docker is absolutely possible and is the more stable long-term solution compared to Windows + WSL2.

However, practical experience shows:

Internally, the Pi-Node behaves more like a packaged distributed system than a simple Docker container.

The most important success factors are:

  • native Linux filesystems
  • stable Docker volumes
  • clean PostgreSQL data
  • working HTTP configuration
  • cautious updates
  • and a one-time activation through the official Windows app

Once these points are properly implemented, the node runs stably, performs well, and is significantly easier to maintain than under WSL2.

Especially the combination of native Linux filesystems, Docker Compose, and a clean separation between node, database, and monitoring results in much greater long-term stability than classic WSL2 installations under Windows.

Anyone who wants to operate the node productively and permanently should therefore switch to a native Linux Docker environment as early as possible.

Donate Bild

Support / Donation Link for the Channel
If my posts have been helpful or supported you in any way, I’d truly appreciate your support 🙏

PayPal Link
Bank transfer, Bitcoin and Lightning

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

Tags: , , , , , , ,

Leave a Reply