Linux Node Installation Instructions

Prerequisites for Linux Node

Make sure you meet all the prerequisites.

Docker and Docker Compose v2 are required to use this project.

See below for instructions on how to set up the new Linux Node and how to upgrade pre-existing Nodes (if you have Nodes running on a Linux machine already).

Set Up New Nodes

Here are step-by-step instructions to add the Pi Network APT repository and install packages from it.

1) Install prerequisites

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

2) Add the repository GPG key

• Create keyring directory, download and dearmor the key, then make it readable

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://apt.minepi.com/repository.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/pinetwork-archive-keyring.gpg
sudo chmod a+r /etc/apt/keyrings/pinetwork-archive-keyring.gpg

3) Add the APT source

• Use the default Linux architecture (amd64); the repository is available at https://apt.minepi.com

echo 'deb [arch=amd64 signed-by=/etc/apt/keyrings/pinetwork-archive-keyring.gpg] https://apt.minepi.com stable main' | sudo tee /etc/apt/sources.list.d/pinetwork.list > /dev/null

4) Update package index

sudo apt-get update

5) Install a package from the repo

sudo apt-get install -y pi-node

6) Verify the installation

pi-node --version

7) Discover pi-node CLI commands

pi-node --help

8) Initialize pi-node

• CLI has built-in help; see pi-node –help for more info
• Run the following command to initialize pi-node

pi-node initialize
For more informations use pi-node initialize –help

Should I use auto-update?

Autoupdate will automatically update your Mainnet node to the latest version when a new version is released
and perform all required migrations. Some migrations may take few hours to complete. If you want to have
more control over the update process, you should disable auto-update and use pi-node updateNode command to perform
updates.

Upgrade Pre-Existing Nodes

This sections is for those with Nodes running on a Linux machine already.

To use your previous node configuration with the CLI, first follow the step-by-step setup on Ubuntu up to Step 7.

Then, follow the backwards compatibility instructions:

1) Collect your existing values

• node_seed (from mainnet.env or stellar-core.cfg)
• postgres password (from mainnet.env)
• docker volumes path (from your old docker-compose.yml)

Helpful commands to locate values:

grep -E '^(NODE_SEED|NODE_PRIVATE_KEY)=' ./mainnet.env

docker exec mainnet grep -E 'NODE_SEED' ./stellar-core.cfg

grep -E '^POSTGRES_PASSWORD=' ./mainnet.env

grep -nE 'volumes:|docker_volumes|/opt/stellar|/var/log/supervisor' ./docker-compose.yml

2) Stop your existing node (and back up volumes)

docker compose down

Optional: backup volumes with cp preserving attributes and permissions:

cp -a docker_volumes docker_volumes.backup

3) Initialize your node with the CLI (re-using existing config)

Interactive (you will be asked for the above values):

pi-node initialize

Non-interactive (provide all values up front; recommended for partners/automation):

pi-node initialize --pi-folder "$HOME/pi-node" --docker-volumes "./docker_volumes/mainnet" --node-seed "<seed>" --postgres-password "<password>" --start-node

4) Verify and manage the node

pi-node status

docker compose -f "$HOME/pi-node/docker-compose.yml" logs -f

docker compose -f "$HOME/pi-node/docker-compose.yml" restart

docker compose -f "$HOME/pi-node/docker-compose.yml" down

Notes

• Always keep your NODE_SEED secret. Do not share it.
• Ensure the DOCKER_VOLUMES_PATH matches your old setup before running initialize.