I'm maintaining an Unraid Community Applications (CA) template for running the Pi Network Node on Unraid (mainnet), via the BitCryptic wrapper image with performance tuning baked in.

Repo (template + docs):

https://github.com/bitcryptic-gw/unraid-pi-network-node

Docker Hub:

https://hub.docker.com/r/bitcryptic/pi-network-node

Install via Community Applications — search for "Pi Network Node", or add this repository manually in CA settings:

https://raw.githubusercontent.com/bitcryptic-gw/unraid-pi-network-node/main/PiNetworkNode.xml

What the BitCryptic wrapper adds

The template uses bitcryptic/pi-network-node rather than the upstream image directly. This bakes in three performance tuning env vars that significantly reduce CPU load on the host:

- INGEST_DISABLE_STATE_VERIFICATION=true — disables periodic full ledger state scans (main CPU reduction)

- PARALLEL_JOB_SIZE=1 — reduces horizon ingestion worker parallelism

- HISTORY_RETENTION_COUNT=1000000 — retains ~8 weeks of ledger history instead of full history since genesis

The latest tag always tracks the current Pi node release. Versioned tags (e.g. v22.1) are also available for pinning.

Template notes

- Persistent data: required mapping to /opt/stellar (Unraid appdata recommended)

- Ports mapped (standard): 31401 (Horizon HTTP), 31402 (stellar-core peer), 31403 (local history / webfsd)

- Required env var: POSTGRES_PASSWORD

- Optional env var: NODE_PRIVATE_KEY (migration only — do not run two nodes with the same key)

- Mainnet flags passed as Post Arguments: --mainnet --enable-auto-migrations

If you need help, please include:

- Unraid version

- Container startup log (first ~200 lines after start)

- docker ps --format '{{.Names}}\t{{.Ports}}'

- Your /opt/stellar host path mapping

Disclaimer: Community-maintained template; not affiliated with or endorsed by Pi Core Team.

Edited April 18Apr 18 by BitCryptic
added clarifying points

Please consider including this in Unraid' CA

Template has been updated to latest docker image, includes required version increase as of 1st March 2026 for Pi Network nodes.

Thanks for your work. I know the Linux node doesn't generate any rewards, is that correct?

You get rewards - or at least a multiplier of your existing daily rewards, if you generate a NODE_PRIVATE_KEY elsewhere first and you add that in the docker template. You'll find that option to add it in the 'Show more settings...' section of my template. It's a bit convoluted right now to generate the key and pair with your Pi app on mobile but it can certainly be done. In summary, you need to go through the initial steps of installing a node on Windows or Mac. You don't need to let it run and download the whole chain history etc - you just need to initialise and pair with your app. Then extract the private key from that node, shut it down - then paste that key into your Unraid hosted docker node. If you start a linux/docker node with that NODE_PRIVATE_KEY field empty, then a key will be generated for you. Hopefully there will be an alternate method of pairing directly with that key sometime and the whole Windows/Mac thing can be avoided. FYI - my current 'to-do' list includes adding a web interface for this Unraid template, to surface some of the node stats/status and include the option to see/copy the private key for safe keeping.

Thanks for the instructions. I wanted to point out that if you're using the organization_mainnet-v1.0-p19.9 version, the node isn't able to sync. I updated to the pinetwork/pi-node-docker:organization_mainnet-v1.0-p20.2 version and it works.

Thanks @zichichi , not sure why my previous update didn't get pushed. I've updated the template and readme to reflect the latest required image again just now. The Pi project timeline is here for reference --> https://docs.google.com/document/d/1iqI7MZCfLqiZMYdGlXSQXpS1qK2q74nVK0jBER-S-mM/edit?tab=t.0

how much memory does/can this use?

I am watching the container at it's up to 15gb atm and climbing.

edit: it's dropped down to 13gb now

edit: now its about 25gb

edit: I saw you say something about a webui, just wondering if there is an eta for that?

edit: are there any console commands to check its status?

Edited March 19Mar 19 by schuu

7 hours ago, schuu said:

how much memory does/can this use?

I am watching the container at it's up to 15gb atm and climbing.

edit: it's dropped down to 13gb now

edit: now its about 25gb

edit: I saw you say something about a webui, just wondering if there is an eta for that?

edit: are there any console commands to check its status?

My active container is using around 2.5GB. It may use more while doing the initial download as the database does a lot of inserts etc. No ETA on the UI, I plan to spend some time on that in the next couple of days. I'll come back to you with some examples of CLI status checks you can do.

my windows vm uses testnet2 and not mainnet

i don't get bonus with this container for whatever reason even after adding my node private key..

and i stopped it because of the high ram usage after a couple of days.

Template updated — v21.2 (image change)

The template has been updated to protocol v21.2, in line with the Pi Core Team's upgrade schedule (deadline: April 6, 2026).

What's changed:

The template now points to a BitCryptic-maintained wrapper image rather than the upstream image directly:

bitcryptic/pi-network-node:v21.2

This image is built from the official Pi Network image (pinetwork/pi-node-docker:organization-mainnet-v1.0-p21.2) with three performance optimisations baked in that significantly reduce host CPU load:

• INGEST_DISABLE_STATE_VERIFICATION=true — disables periodic full ledger state scans (the main CPU reduction)

• PARALLEL_JOB_SIZE=1 — reduces horizon ingestion worker parallelism

• HISTORY_RETENTION_COUNT=1000000 — retains ~8 weeks of ledger history rather than all history since genesis

On our test node this dropped host load average from ~4 to under 1, and horizon CPU from ~57% to under 3%.

The Dockerfile and GitHub Actions build pipeline are open source at https://github.com/bitcryptic-gw/unraid-pi-network-node if you want to inspect what's in the image.

Upgrade notes for this version:

• Quick upgrade, under 5 minutes expected downtime

• No heavy data migration (unlike the 19.x upgrades)

• Verify sync after restart: curl http://localhost:31401 | python3 -m json.tool | grep ingest_latest_ledger and compare against https://api.mainnet.minepi.com

4 hours ago, schuu said:

my windows vm uses testnet2 and not mainnet

i don't get bonus with this container for whatever reason even after adding my node private key..

and i stopped it because of the high ram usage after a couple of days.

I would imagine the bonus earn rate would be tied to running on mainnet, though I'm not sure.

Template updated — v22.1 (image change)

The template has been updated to protocol v22.1, in line with the Pi Core Team's upgrade schedule (deadline: April 27, 2026).

What's changed:

Image updated to: bitcryptic/pi-network-node:v22.1

Wraps the official Pi Network image (pinetwork/pi-node-docker:organization-mainnet-v1.0-p22.1) with the same performance optimisations as previous versions.

Upgrade notes for this version:

• Quick upgrade, under 5 minutes expected downtime

• No heavy data migration

• Existing users: Unraid's "Check for Updates" will detect the new tag automatically — just hit Apply Update

• Verify sync after restart: curl http://localhost:31401 | python3 -m json.tool | grep ingest_latest_ledger and compare against https://api.mainnet.minepi.com

19 hours ago, BitCryptic said:

Template updated — v22.1 (image change)

The template has been updated to protocol v22.1, in line with the Pi Core Team's upgrade schedule (deadline: April 27, 2026).

What's changed:

Image updated to: bitcryptic/pi-network-node:v22.1

Wraps the official Pi Network image (pinetwork/pi-node-docker:organization-mainnet-v1.0-p22.1) with the same performance optimisations as previous versions.

Upgrade notes for this version:

• Quick upgrade, under 5 minutes expected downtime

• No heavy data migration

• Existing users: Unraid's "Check for Updates" will detect the new tag automatically — just hit Apply Update

• Verify sync after restart: curl http://localhost:31401 | python3 -m json.tool | grep ingest_latest_ledger and compare against https://api.mainnet.minepi.com

Template has been updated to use 'latest' tag instead of the specific versions, to make for smoother and easier updates.

Template updated — v23.0.1 (image change)

The template has been updated to protocol v23.0.1, in line with the Pi Core Team's upgrade schedule (deadline: May 15, 2026).

What's changed:

Image updated to: bitcryptic/pi-network-node:latest

Wraps the official Pi Network image ( pinetwork/pi-node-docker:organization-mainnet-v1.0-p23.0.1 ) with the same performance optimisations as previous versions.

Upgrade notes for this version:

- This is a heavier upgrade than previous versions — expect longer startup time than usual

- Includes an in-place PostgreSQL upgrade (v12 → v16) and data migrations on first boot

- Do not interrupt the container while it is starting — allow it to complete fully

- Back up your /opt/stellar volume before upgrading if you haven't already

- Existing users: Unraid's "Check for Updates" will detect the new tag automatically — just hit Apply Update

- Verify sync after restart: curl http://localhost:31401 | python3 -m json.tool | grep ingest_latest_ledger and compare against https://api.mainnet.minepi.com

Template updated — v24.1.0 (image change)

The template has been updated to protocol v24.1.0, in line with the Pi Core Team's upgrade schedule (deadline: June 2, 2026).

What's changed: Image updated to: bitcryptic/pi-network-node:latest Wraps the official Pi Network image ( pinetwork/pi-node-docker:organization-mainnet-v1.0-p24.1.0 ) with the same performance optimisations as previous versions.

Upgrade notes for this version:

• Routine binary bump — stellar-core updated to v24.1.0, horizon to v24.0.0

• No data migrations on first boot for existing users already on v23.x

• Ubuntu base (24.04) and PostgreSQL 16 unchanged

• Existing users: Unraid's "Check for Updates" will detect the new tag automatically — just hit Apply Update

• Verify sync after restart: curl http://localhost:31401 | python3 -m json.tool | grep ingest_latest_ledger and compare against https://api.mainnet.minepi.com

Template updated — v25.2.2 (image change)

The template has been updated to protocol v25.2.2, following the Pi Core Team's latest release.

What's changed: Image updated to: bitcryptic/pi-network-node:latest Wraps the official Pi Network image (pinetwork/pi-node-docker:organization-mainnet-v1.0-p25.2.2) with the same performance optimisations as previous versions.

Upgrade notes for this version:

• Binary bump — stellar-core updated to v25.2.2, horizon to v25.1.0

• No data migrations on first boot — straight binary swap, no pg_upgrade, no reingestion

• Ubuntu base and PostgreSQL 16 unchanged

• Existing users: Unraid's "Check for Updates" will detect the new tag automatically — just hit Apply Update

• Verify sync after restart: docker exec PiNetworkNode node-status (or curl http://localhost:31401 | python3 -m json.tool | grep ingest_latest_ledger and compare against https://api.mainnet.minepi.com)

Template updated — v26.1.0 (image change)

The template has been updated to protocol v26.1.0, following the Pi Core Team's latest release.

What's changed: Image updated to: bitcryptic/pi-network-node:latest Wraps the official Pi Network image (pinetwork/pi-node-docker:organization-mainnet-v1.0-p26.1.0) with the same performance optimisations as previous versions.

Upgrade notes for this version:

• Binary bump — stellar-core updated to v26.1.0, horizon to v26.0.0

• No data migrations on first boot — straight binary swap, no pg_upgrade, no reingestion

• Ubuntu base and PostgreSQL 16 unchanged

• Existing users: Unraid's "Check for Updates" will detect the new tag automatically — just hit Apply Update

• Verify sync after restart: docker exec PiNetworkNode node-status (or curl http://localhost:31401 | python3 -m json.tool | grep ingest_latest_ledger and compare against https://api.mainnet.minepi.com)

Template updated — v27.1.0 (image change)

The template has been updated to protocol v27.1.0, following the Pi Core Team's latest release.

What's changed: Image updated to: bitcryptic/pi-network-node:latest Wraps the official Pi Network image (pinetwork/pi-node-docker:organization-mainnet-v1.0-p27.1.0) with the same performance optimisations as previous versions.

Upgrade notes for this version:

• Binary bump — stellar-core updated to v27.1.0, horizon to v27.0.0

• No data migrations on first boot — straight binary swap, no pg_upgrade, no reingestion

• Ubuntu base and PostgreSQL 16 unchanged

• Existing users: Unraid's "Check for Updates" will detect the new tag automatically — just hit Apply Update

• Verify sync after restart: docker exec PiNetworkNode node-status (or curl http://localhost:31401 | python3 -m json.tool | grep ingest_latest_ledger and compare against https://api.mainnet.minepi.com)

• Note: stellar-core's own sync state is more reliably checked via docker exec PiNetworkNode curl -s http://localhost:11626/info — look for "state" : "Synced!" — since horizon's root endpoint can briefly show stale core_latest_ledger/current_protocol_version values right after a restart before it catches up to core's actual state

Template + image updated: Protocol 28 (p28.0.1), and a correction to the history-retention setting

1. Upstream bumped to Protocol 28

bitcryptic/pi-network-node:latest now wraps pinetwork/pi-node-docker:organization-mainnet-v1.0-p28.0.1:

• stellar-core: v27.1.0 → v28.0.1

• horizon: v27.0.0 → v28.0.1

• PostgreSQL: 16 (unchanged)

This is a straight binary swap: no pg_upgrade, no schema migration, no reingestion, and no config changes. Downtime is just the container restart, usually a few minutes; let it finish if it takes longer. Ports, mounts and variables are unchanged.

Pi mainnet hasn't activated protocol 28 on-ledger yet, so Horizon will report current_protocol_version: 27 with supported_protocol_version: 28. That is expected.

2. History retention is now really 125000, and PARALLEL_JOB_SIZE is gone

The template has claimed HISTORY_RETENTION_COUNT=125000 for a while, but that value was never actually in effect:

• Horizon starts via a script that sources /opt/stellar/horizon/etc/horizon.env, and that file overrides the container environment.

• On a fresh install, upstream's stock horizon.env sets HISTORY_RETENTION_COUNT=0 ("keep everything"), which also disables Horizon's lookup-table reaping, so the database grew without limit.

The image now ships a stock horizon.env with 125000, so new installs get the documented value. That is roughly 7 days of history at ~5 s per ledger.

Existing installs: your appdata copy of horizon.env is never rewritten by the image, so check it:

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

The last HISTORY_RETENTION_COUNT= line is the one that applies. If it says 0 or something very large, add export HISTORY_RETENTION_COUNT=125000 at the end of the file and restart the container. To check what you're actually keeping:

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

The difference between history_latest_ledger and history_elder_ledger is your retention window. After lowering it, Horizon's reaper starts within about an hour and deletes the excess in one continuous run, which can mean heavy disk I/O for a while; schedule it for a quiet time. The deletes free space inside Postgres but don't shrink the files on disk.

Also removed: PARALLEL_JOB_SIZE. The template claimed it reduced ingestion parallelism, but Horizon dropped that option in v22, so it did nothing. It's gone from the image, README and template.

How to update

docker pull bitcryptic/pi-network-node:latest

Then in the Unraid Docker tab, stop and remove PiNetworkNode (tick "remove image") and recreate it from the template, or use Check for Updates → Apply Update. Don't use Restart to pick up a new image; a recreate is what applies it.

More detail, including how to check the effective tuning values, is in the README: https://github.com/bitcryptic-gw/unraid-pi-network-node

As always, this is a community-maintained template, not affiliated with or endorsed by the Pi Core Team.

Edited October 12Oct 12 by BitCryptic
markdown formatting fix