Step 1: Prepare Prerequisites

Server minimum specifications
150GB disk space, to start (Ideally 300GB)
4 vCPUs
4GB RAM
A recent Debian-based Linux distribution (Suggested: Ubuntu 24.04 (LTS) x64)

Docker prerequisites
A working Docker installation: see https://docs.docker.com/engine/install/
A working Docker Compose v2 plugin: see https://docs.docker.com/compose/install/linux/#install-using-the-repository

APT prerequisites

# Install APT prerequisites
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# 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 update-protocol

command to perform updates.

Existing Nodes: Upgrade Instructions

If you are upgrading, 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)

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-private-key "<seed>" --postgres-password "<password>" --start-node

Pi Node Usage

# Access built-in help
pi-node --help

Common useful commands below

pi-node logs -f         # Follow container logs
pi-node stop            # Stop node containers
pi-node start           # Start node containers
pi-node restart         # Restart node containers
pi-node status          # Check node status
pi-node update-protocol # Update this node to the latest protocol version by updating its Docker container.

# Upgrade Linux CLI package
sudo apt-get update
sudo apt-get install --only-upgrade pi-node

Note: Always keep your NODE_SEED secret. Do not share it.