Skip to main content

Mina Protocol Mainnet Validator Setup Guide

This guide provides two methods to set up a Mina Protocol block producer node on the mainnet. Choose the method that best fits your environment.

Prerequisites​

System Requirements​

  • CPU: 8 cores with BMI2 and AVX instruction sets
  • Memory: 32GB RAM minimum
  • Storage: 64GB minimum (SSD recommended)
  • Network: 1 Mbps stable internet connection
  • Access: Root or sudo privileges

Network Information​

ComponentValueDescription
NetworkMina MainnetProduction network
Latest Version3.1.0Current mainnet version
Token SymbolMINANative token
Block Time~3 minutesAverage block time

Installation Methods​

Choose one of the following installation methods:

  • OS: Any Linux distribution with Docker support
  • Pros: Easy setup, isolated environment, no OS dependency
  • Cons: Requires Docker knowledge

Method 2: Systemd (Native)​

  • OS: Ubuntu 22.04 LTS x64 (required)
  • Pros: Native performance, direct system integration
  • Cons: OS-specific, more complex setup
tip

The following commands are executed as root by default. If you are not a root user, please prepend the commands with sudo.

Update System Packages​

sudo -i

# Update package list and install required tools
apt update
apt install -y make git-core libssl-dev pkg-config build-essential protobuf-compiler libudev-dev curl jq wget aria2

Method 1: Docker Compose Installation​

This method uses Docker Compose for easy deployment and management, based on the minadeploy project.

Step 1: Install Docker​

# Update system packages and install prerequisites
apt-get update
apt-get install ca-certificates curl

# Add Docker's official GPG key
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update package list and install Docker
apt-get update
apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start and enable Docker service
systemctl start docker
systemctl enable docker

# Verify installation
docker --version
docker compose version

Step 2: Clone the Repository​

# Clone the minadeploy repository
git clone https://github.com/ronnynth/minadeploy.git
cd minadeploy

# Set environment variables
export RUNDIR=$(pwd)

export DOCKER_IMAGE="minaprotocol/mina-daemon:3.1.0-ae112d3-bullseye-mainnet"
info

Find the latest mina image here: Releases

info

The minadeploy project provides a quick way to deploy a Mina blockchain node using Docker Compose. It includes pre-configured Docker Compose files and supports custom key, port, and parameter configuration.

Note: This guide uses docker compose (without hyphen) which is the newer Docker Compose V2 syntax. If you're using an older version, you may need to use docker-compose (with hyphen) instead.

Step 3: Configure Environment Variables​

Create a .env file in the project root directory:

cat > .env << EOF
IMAGE=${DOCKER_IMAGE}
P2P_PORT=8302
METRICS_PORT=6060
MINA_PRIVKEY_PASS=your_secure_password
RUNDIR=${RUNDIR}
COINBASE_RECEIVER=B62qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EOF
info

Environment Variables:

  • IMAGE: Mina node image name and tag
  • P2P_PORT: P2P network port (default: 8302)
  • METRICS_PORT: Metrics port (default: 6060)
  • MINA_PRIVKEY_PASS: Wallet private key password
  • RUNDIR: Absolute path to the project directory
  • COINBASE_RECEIVER: Address to receive block rewards (your wallet address)
tip

Update .env file: Replace COINBASE_RECEIVER in your .env file with the public key from above.

Step 4: Prepare Your Wallet Key (Optional)​

warning

Key Requirement: You need a Mina wallet private key to run a block producer node. If you don't have one yet, you can generate it using the steps below. If you already have a key, skip to the "existing key" section.

If you don't have a Mina wallet key yet, you can generate one:

# Generate new key pair using Docker
docker run --rm --entrypoint "" \
  -v ${RUNDIR}/keys:/keys \
  -e "MINA_PRIVKEY_PASS=your_secure_password" \
  $DOCKER_IMAGE \
  mina advanced generate-keypair --privkey-path /keys/my-wallet

# Set proper permissions
chmod -R 700 ${RUNDIR}/keys

# Get your public key (wallet address)
docker run --rm --entrypoint ""\
  -v ${RUNDIR}/keys:/keys \
  -e "MINA_PRIVKEY_PASS=your_secure_password" \
  $DOCKER_IMAGE \
  mina advanced validate-keypair --privkey-path /keys/new-wallet

If you already have a Mina wallet key:

# Copy your existing key to the keys directory
cp /path/to/your/existing-key ${RUNDIR}/keys/my-wallet

# Set proper permissions
chmod -R 700 ${RUNDIR}/keys

Step 5: Start the Node​

warning

If you need to access the limited GraphQL server, you must set --open-limited-graphql-port in the command line and map port 3095. Note: this is INSECURE, make sure your firewall is configured correctly.

ports:
  - ${LIMITED_GRAPHQL_PORT}:3095

# add in command
--file-log-level Debug --open-limited-graphql-port
# Start the Mina node
docker compose up -d

# Check container status
docker compose ps

# View logs
docker compose logs -f

Step 6: Monitor Your Node​

# Check node status
docker exec mina-node mina client status

# Check sync status
docker exec mina-node mina client status | grep "Sync Status"

# Check peer connections
docker exec mina-node mina client status | grep "Peers"

# Stop the node (if needed)
docker compose down

Method 2: Systemd Installation (Ubuntu 20.04 Only)​

This method installs Mina daemon natively on Ubuntu 20.04, based on the official Mina documentation.

Step 1: Install Mina Daemon​

# Add Mina repository
rm /etc/apt/sources.list.d/mina*.list
echo "deb [trusted=yes] http://packages.o1test.net $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/mina.list

# Update package list
apt update

# Install Mina daemon
apt install -y mina-mainnet=3.1.0-ae112d3

Step 2: Generate Wallet Key Pair​

# Create keys directory
mkdir -pv ~/.keys
cd ~/.keys

# Generate key pair
mina advanced generate-keypair --privkey-path ~/.keys/my-wallet

# Set proper permissions
chmod -R 700 ~/keys

# Get your public key
mina advanced  validate-keypair  --privkey-path ~/.keys/my-wallet

Step 3: Configure Environment​

# Create .mina-env file
cat > ~/.mina-env << EOF
MINA_PRIVKEY_PASS="your_secure_password"
LOG_LEVEL=Info
FILE_LOG_LEVEL=Debug
EXTRA_FLAGS=" --block-producer-key ~/.keys/my-wallet --coinbase-receiver you-coinbase-address --uptime-submitter-key ~/.keys/my-wallet --uptime-url https://uptime-backend.minaprotocol.com/v1/submit"
PEER_LIST_URL=https://bootnodes.minaprotocol.com/networks/mainnet.txt"
EOF

# Set proper permissions
chmod 600 ~/.mina-env

Step 4: Start with Systemd​

# Reload systemd configuration
systemctl --user daemon-reload

# Start mina service
systemctl --user start mina

# Enable auto-start on boot
systemctl --user enable mina

# Enable lingering (keeps service running after logout)
loginctl enable-linger

# Check service status
systemctl --user status mina

Step 5: Monitor Your Node​

# Check node status
mina client status

# View logs
journalctl --user -u mina -f

# Check sync status
mina client status | grep "Sync Status"

# Stop the service (if needed)
systemctl --user stop mina

Directory Structure​

Docker Compose Method​

minadeploy/
├── .env                    # Environment configuration
├── docker-compose.yaml    # Docker Compose configuration (from repository)
├── keys/                   # Wallet keys directory
│   └── my-wallet          # Your private key file
├── .mina-config/          # Node data and logs
└── README.md              # Project documentation

Systemd Method​

~/
├── .mina-env              # Environment configuration
├── keys/                  # Wallet keys directory
│   └── my-wallet         # Your private key file
└── .mina-config/         # Node data and logs

Common Operations​

Check Node Status​

# Docker Compose method
docker exec mina-node mina client status

# Systemd method
mina client status

View Logs​

# Docker Compose method
docker compose logs -f

# Systemd method
journalctl --user -u mina -f

Restart Node​

# Docker Compose method
docker compose restart

# Systemd method
systemctl --user restart mina

Troubleshooting​

Common Issues​

Port Conflicts​

# Check what's using the ports
ss -tulpn | grep :8302
ss -tulpn | grep :6060

# For Docker method: change P2P_PORT and METRICS_PORT in .env
# For systemd method: add port flags to EXTRA_FLAGS

Permission Issues​

# Fix key permissions
chmod -R 700 keys         # or ~/keys

Node Not Syncing​

# Check peer connections
# Docker: docker exec mina-daemon mina client status | grep "Peers"
# Systemd: mina client status | grep "Peers"

# Should show at least 1-10 peers

Getting Help​

If you encounter issues:

  1. Check logs for error messages
  2. Verify configuration files and permissions
  3. Test network connectivity and port availability
  4. Join the community for support:
info

Choose the installation method that best fits your environment. Docker Compose is recommended for most users due to its simplicity and portability.

warning

Security Notes:

  • Keep your private key secure and never share it
  • Use a strong password for MINA_PRIVKEY_PASS
  • Backup your key file to a secure location
  • Regularly update your node to the latest version