Step-by-step instructions to install Pi Node on Linux.
Step 1: Prepare APT prerequisites
# Install APT prerequisites
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo apt-get install docker
# Add Pi Node’s official GPG key (https://apt.minepi.com/repository.gpg.key)
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
# Add Pi Node’s APT source (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
# Update APT package index
sudo apt-get update
Step 2: Install the Pi Node package
sudo apt-get install pi-node
# Verify installation
pi-node --version
Step 3: Node initialization
# Access built-in help
pi-node --help
See below for instructions to start your node. For new node installations continue here. If you are upgrading your existing node, continue here.
New Nodes: Initialization Instructions
# Initialize pi-node
pi-node initialize
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 a few hours to complete. If you want to have more control over the update process, you should not enable auto update and use the
pi-node updateExisting Nodes: Upgrade Instructions
Use your previous node configuration with the CLI by following the steps below.
Step 1: Collect your existing configuration settings
node_seed (from mainnet.env or stellar-core.cfg)
grep -E '^(NODE_SEED|NODE_PRIVATE_KEY)=' ./mainnet.env
docker exec mainnet grep -E 'NODE_SEED' ./stellar-core.cfg
postgres password (from mainnet.env)
grep -E '^POSTGRES_PASSWORD=' ./mainnet.env
docker volumes path (from your old docker-compose.yml)
grep -nE 'volumes:|docker_volumes|/opt/stellar|/var/log/supervisor' ./docker-compose.yml
Step 2: Stop your existing node
docker compose down
Optional: backup volumes with cp preserving attributes and permissions. This step may take a long time and could exhaust your disk space. It is optional. Example command to back up:
cp -a <docker_volumes> <docker_volumes.backup>
Step 3: Initialize your node with the CLI (re-using existing config) Interactive (you will be asked for the above values)
Ensure the DOCKER_VOLUMES_PATH matches your old setup before running initialization:
Interactive
pi-node initialize
Non-interactive (Alternative that provides all values up front; useful for automation):
pi-node initialize --pi-folder "$HOME/pi-node" --docker-volumes "./docker_volumes/mainnet" --node-seed "<seed>" --postgres-password "<password>" --start-node
Pi Node Usage
# Access built-in help
pi-node --help
Docker logs mainnet -f
Docker stop mainnet
Docker start mainnet
Docker restart mainnet
Note: Always keep your NODE_SEED secret. Do not share it.
