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