Pi-Network-Node

Pi-Network-Node

Docker app from BitCryptic's Repository

Pi Network Node (Docker) template for Unraid — maintained by BitCryptic.

Overview
Pi Network Node (Docker) template for Unraid — maintained by BitCryptic. This image wraps the official Pi Network node image with performance tuning applied out of the box, significantly reducing CPU and host load compared to running the upstream image directly. Upstream image: pinetwork/pi-node-docker:organization-mainnet-v1.0-p28.0.1 Source / changelog: https://github.com/bitcryptic-gw/Unraid-pi-network-node Performance optimisations included: - INGEST_DISABLE_STATE_VERIFICATION=true — disables periodic full ledger state scans (main CPU reduction) - HISTORY_RETENTION_COUNT=125000 — prunes horizon history to the most recent 125000 ledgers (~7 days at ~5s per ledger) instead of retaining all history since genesis Persistent data: - Map a host path to /opt/stellar (required). Ports (Pi standard): - 31401 -> 8000 (Horizon HTTP) - 31402 -> 31402 (stellar-core peer) - 31403 -> 1570 (Local history server / webfsd) Notes: - POSTGRES_PASSWORD is required. - NODE_PRIVATE_KEY is optional (advanced): leave blank for new nodes; set only if migrating an existing node identity. - --mainnet and --enable-auto-migrations are passed as Post Arguments. - Horizon reads its tuning from horizon.env inside your appdata, which overrides the image defaults; the README explains how to check the effective values.

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:
  • 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.

  1. 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"

Optional: secrets from files (*_FILE)

Both secrets can be supplied as files on disk instead of as environment variables, so they no longer appear in docker inspect or in the Unraid template:

environment variable file equivalent
POSTGRES_PASSWORD POSTGRES_PASSWORD_FILE
NODE_PRIVATE_KEY NODE_PRIVATE_KEY_FILE

Point the *_FILE variable at a path inside the container (normally a read-only bind mount). The wrapper entrypoint reads it and hands the value to upstream /start in the environment, because that is the only channel upstream understands.

This is opt-in and off by default. If no *_FILE variable is set — or both are set to the empty string — the wrapper does nothing at all and execs upstream /start with your environment untouched.

*_FILE set? init marker present? what the wrapper does
none set either way no-op; upstream /start runs with the plain environment (an unset NODE_PRIVATE_KEY still auto-generates a seed, as upstream documents)
set present validates the file, does not read or export the value — the node is already initialised, and upstream only reads these secrets on its first-init path
set absent validates, reads, strips one trailing LF/CRLF, and exports the value for the first-init run

Each secret is gated on its own marker, never a shared one:

  • NODE_PRIVATE_KEY → /opt/stellar/core/.quickstart-initialized
  • POSTGRES_PASSWORD → /opt/stellar/postgresql/.quickstart-initialized

If both X and X_FILE are set, the file wins and the log names the variable but never the value.

On an uninitialised node, setting one *_FILE means the other secret also needs a source. When a marker is absent the wrapper exports that value for the first-init run, and upstream cannot initialise with only one of the two secrets — so with both markers absent, NODE_PRIVATE_KEY_FILE alone still needs POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE (and vice versa), or the container refuses to start with exit code 78. On an already-initialised node nothing is exported, so a single file on its own is fine.

The container refuses to start (exit code 78) when a *_FILE is set and the file is missing, is a symlink, is not a regular file, is owned by anything other than uid 0, has any group or other permission bit (mode must be 0400 or 0600), is empty, is empty after stripping the trailing newline, contains an embedded newline, or exceeds 4096 bytes. It also refuses when a needed value has no source at all — that prevents upstream silently generating a new node identity if an init marker is ever lost.

Example (Unraid template), secrets written by the operator as 0400 root:root in a 0700 directory:

Path:      /mnt/cache/appdata/secrets/pi-node-mainnet-unraid-syd  ->  /run/secrets   (read only)
Variable:  NODE_PRIVATE_KEY_FILE     = /run/secrets/node-private-key
Variable:  POSTGRES_PASSWORD_FILE    = /run/secrets/postgres-password

The entrypoint tests are in the project record; the log lines it emits look like:

pi-node-entrypoint: NODE_PRIVATE_KEY_FILE: ok (mode 0400, uid 0, 57 bytes)
pi-node-entrypoint: NODE_PRIVATE_KEY: not exported (already initialised: /opt/stellar/core/.quickstart-initialized)
pi-node-entrypoint: refused: POSTGRES_PASSWORD_FILE: mode is 0644, must have no group or other permission bits (0400 or 0600) (/run/secrets/postgres-password)

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.

Categories

Download Statistics

2,090
Total Downloads

Related apps

Explore more like this

Explore all

Links

Details

Repository
bitcryptic/pi-network-node:latest
Last Updated2026-10-11
First Seen2026-05-13

Runtime arguments

Web UI
http://[IP]:[PORT:8000]/
Network
bridge
Shell
sh
Privileged
false

Template configuration

/opt/stellarPathrw

Persistent node data (required).

Default
/mnt/cache/appdata/pi-node-mainnet/stellar
/var/log/supervisor (optional)Pathrw

Optional: persist supervisor logs.

Target
/var/log/supervisor
Default
/mnt/cache/appdata/pi-node-mainnet/supervisor_logs
POSTGRES_PASSWORDVariable

Required. Database password for the node (keep secret).

NODE_PRIVATE_KEY (optional)Variable

Optional (advanced). Existing node private key for migrations. Leave blank for new nodes; key will be auto-generated.

Target
NODE_PRIVATE_KEY
Horizon HTTP (host 31401)Porttcp

Horizon HTTP (Pi standard). Forward this on your router if required by Pi port checks.

Target
8000
Default
31401
Stellar peer (host 31402)Porttcp

stellar-core peer port (Pi standard). Forward this on your router if required by Pi port checks.

Target
31402
Default
31402
Local history server (host 31403)Porttcp

Local history server / webfsd (Pi standard). Forward this on your router if required by Pi port checks.

Target
1570
Default
31403