Pi-Network-Node
Docker app from BitCryptic's Repository
Pi Network Node (Docker) template for Unraid — maintained by BitCryptic.
Overview
Readme
View on GitHubPi 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(wrapspinetwork/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:
- 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.
- 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)
- Add the template XML to your Unraid flash drive templates folder (or install via CA once published).
- Create/choose a persistent appdata path for
/opt/stellar(example):/mnt/cache/appdata/pi-node-mainnet/stellar - Set
POSTGRES_PASSWORD(required). - (Optional) Set
NODE_PRIVATE_KEYonly if you are migrating an existing node identity. - 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-initializedPOSTGRES_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
Related apps
Explore more like this
Explore allLinks
Details
bitcryptic/pi-network-node:latestRuntime arguments
- Web UI
http://[IP]:[PORT:8000]/- Network
bridge- Shell
sh- Privileged
- false
Template configuration
Persistent node data (required).
- Default
- /mnt/cache/appdata/pi-node-mainnet/stellar
Optional: persist supervisor logs.
- Target
- /var/log/supervisor
- Default
- /mnt/cache/appdata/pi-node-mainnet/supervisor_logs
Required. Database password for the node (keep secret).
Optional (advanced). Existing node private key for migrations. Leave blank for new nodes; key will be auto-generated.
- Target
- NODE_PRIVATE_KEY
Horizon HTTP (Pi standard). Forward this on your router if required by Pi port checks.
- Target
- 8000
- Default
- 31401
stellar-core peer port (Pi standard). Forward this on your router if required by Pi port checks.
- Target
- 31402
- Default
- 31402
Local history server / webfsd (Pi standard). Forward this on your router if required by Pi port checks.
- Target
- 1570
- Default
- 31403