Pi Network Node (Unraid Template)

Unraid Community Applications (CA) template for running the Pi Network Node on Unraid (mainnet), via the BitCryptic wrapper image with performance tuning baked in. This repo provides:

• An Unraid Docker template XML for bitcryptic/pi-network-node:v28.0.1 (wraps pinetwork/pi-node-docker:organization-mainnet-v1.0-p28.0.1)
• Basic setup notes and common troubleshooting tips

What this template does

• Runs the node in persistent mode by mapping a host path to /opt/stellar (required) https://hub.docker.com/r/pinetwork/pi-node-docker
• Exposes the three standard ports used by the node container:
  • 31401 -> 8000 (Horizon HTTP)
  • 31402 -> 31402 (stellar-core peer)
  • 31403 -> 1570 (Local history server / webfsd) https://hub.docker.com/r/pinetwork/pi-node-docker
• Uses container runtime arguments (--mainnet --enable-auto-migrations) as Post Arguments (so they are passed after the image name), which is required for correct Docker argument ordering.
• Applies horizon performance tuning out of the box:
  • INGEST_DISABLE_STATE_VERIFICATION=true — disables periodic full ledger state scans (main CPU reduction)
  • HISTORY_RETENTION_COUNT=125000 — prunes horizon's history tables to the most recent 125000 ledgers (~7 days at ~5s per ledger) instead of retaining all history since genesis

Where the effective tuning values actually come from

Horizon is launched by /opt/stellar/horizon/bin/horizon, which does:

source /opt/stellar/horizon/etc/horizon.env
exec /usr/bin/stellar-horizon $@

Because that source runs after the container environment exists, the values in the persisted appdata horizon.env win over the image's ENV. On a fresh install this image seeds that file with HISTORY_RETENTION_COUNT=125000; an existing appdata directory keeps whatever it already contains, because this image never rewrites it.

To check the effective values on a running node:

1. Read the file horizon actually sources:

docker exec PiNetworkNode cat /opt/stellar/horizon/etc/horizon.env

On the host that is <appdata>/horizon/etc/horizon.env. It contains an earlier stock line export HISTORY_RETENTION_COUNT=0 near the top and the tuning block at the end — the last matching line in the file wins.

2. Confirm it at runtime from Horizon's root endpoint — the retained window is history_latest_ledger - history_elder_ledger, which should settle at about 125000:

docker exec PiNetworkNode curl -s http://localhost:8000/ | grep -E 'history_(latest|elder)_ledger'

A much larger gap just means the reaper has not caught up yet. The reaper starts within about an hour of a retention change (it triggers when the ingested ledger count is a multiple of 720) and then removes the whole excess in one continuous run — 50,000 ledgers per batch, with a one-second pause between batches. That is sustained heavy disk I/O, so make a retention change at a quiet time (an 875,000-ledger backlog took about 23 minutes to clear). Note also that these deletes free space inside Postgres for reuse but do not shrink the files on disk: only a VACUUM FULL returns that space to the filesystem.

Quick start (Unraid)

1. Add the template XML to your Unraid flash drive templates folder (or install via CA once published).
2. Create/choose a persistent appdata path for /opt/stellar (example): /mnt/cache/appdata/pi-node-mainnet/stellar
3. Set POSTGRES_PASSWORD (required).
4. (Optional) Set NODE_PRIVATE_KEY only if you are migrating an existing node identity.
5. Start the container and wait for initial database setup + migrations to complete.

Configuration

Pi Docker image docs: https://hub.docker.com/r/pinetwork/pi-node-docker

POSTGRES_PASSWORD (required)

Database password for the node's Postgres instance (do not share). This must be set. Choose your own.

NODE_PRIVATE_KEY (optional, advanced: migration only)

Set this only if you are migrating/re-using an existing node identity. Leave it blank for a brand-new node (the container will auto-generate one if not provided). Important: Do not run two nodes with the same NODE_PRIVATE_KEY at the same time.

Back up your node key (recommended for new nodes)

If you start a new node without setting NODE_PRIVATE_KEY, a key/seed is auto-generated. Retrieve it using one of the methods below, back it up somewhere safe and never share it (treat it like a password). Method 1 (host side, if mainnet.env exists under your persisted data): grep -E '^(NODE_SEED|NODE_PRIVATE_KEY)=' /mnt/cache/appdata/pi-node-mainnet/stellar/mainnet.env Method 2 (inside the container, from stellar-core.cfg): docker exec PiNetworkNode sh -lc "grep -E 'NODE_SEED|NODE_PRIVATE_KEY' /opt/stellar/core/etc/stellar-core.cfg"

Ports

Only these ports are mapped by this template:

• 31401/tcp
• 31402/tcp
• 31403/tcp Note: The stellar-core admin port (11626) is intentionally not mapped in this template.

Support

https://forums.unraid.net/topic/197354-pi-network-node-docker-unraid-template-mainnet/

Support the Template Maintainer

If this template saved you time, consider buying me a coffee: https://buymeacoffee.com/bitcryptic

Disclaimer

This is a community-maintained Unraid template and is not affiliated with Pi Core Team. "Pi", "Pi Network", and the Pi logo are trademarks of Pi Community Company. This project is community-maintained and not affiliated with or endorsed by Pi.