본문으로 건너뛰기

Linux Host-Native Installation

This guide covers installing and running monod natively on a Linux host using systemd for process management. This is the recommended approach for production validators.

Recommended Tool

For a streamlined setup experience, use Monarch CLI which handles installation, configuration, and process management automatically.

Prerequisites​

Before installing Monolythium, ensure your system meets these requirements:

System Requirements​

  • OS: Ubuntu 24.04 LTS or later (other distributions supported)
  • Architecture: x86_64 (amd64) or ARM64
  • CPU: 4+ cores recommended for validators
  • RAM: 16GB+ recommended
  • Storage: 500GB+ SSD (NVMe recommended for validators)

Software Prerequisites​

If downloading pre-built binaries:

  • No additional dependencies required

If building from source:

  • Go 1.24.2+ (required for building monod)
Go Version

Use Go 1.24.2 or later. Go 1.24.0 has compatibility issues with some dependencies.

Install Go:

# Download Go 1.24.2 (or latest 1.24.x from https://go.dev/dl/)
wget https://go.dev/dl/go1.24.2.linux-amd64.tar.gz

# Remove old Go installation (if exists)
sudo rm -rf /usr/local/go

# Extract new Go
sudo tar -C /usr/local -xzf go1.24.2.linux-amd64.tar.gz

# Add to PATH
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

# Verify installation
go version
# Expected: go version go1.24.2 linux/amd64

Network Requirements​

Ensure the following ports are open:

PortProtocolPurpose
26656TCPP2P (LythiumBFT)
26657TCPRPC (LythiumBFT)
1317TCPREST API (Cosmos SDK)
9090TCPgRPC
8545TCPEVM JSON-RPC
8546TCPEVM WebSocket

For production deployments, run monod as a dedicated non-root user:

# Create monod user with no login shell
sudo useradd -r -s /bin/false monod

# Create home directory
sudo mkdir -p /home/monod
sudo chown monod:monod /home/monod

# Create data directory
sudo mkdir -p /home/monod/.monod
sudo chown -R monod:monod /home/monod/.monod

This isolates the node process and improves security.

File Permissions

If using a dedicated user, all monod commands must be run as that user:

sudo -u monod monod <command>

Alternatively, set up sudo access or use su - monod for interactive sessions.

Monarch CLI is the recommended tool for node operators. It replaces the deprecated Mono Commander and provides a complete node management experience with built-in process management via OxidePM.

Install Monarch​

# Download binary
```bash
curl -fsSL https://raw.githubusercontent.com/monolythium/monarch-cli/prod/scripts/install.sh | bash

Or build from source:

```bash

Monarch handles:

  • Joining networks with automatic genesis verification
  • Process management via OxidePM (replaces manual systemd management)
  • Node health monitoring with monarch doctor
  • Validator operations (register, edit, unjail)

See the Monarch CLI documentation for complete usage.

monod Binary​

Download Binary​

Download the official pre-built binary:

# Check latest release
LATEST=$(curl -s https://api.github.com/repos/mono-experimental/mono-core/releases/latest | jq -r '.tag_name')

# Download for Linux amd64
curl -LO https://github.com/mono-experimental/mono-core/releases/download/${LATEST}/monod-linux-amd64

# Make executable
chmod +x monod-linux-amd64

# Move to path
sudo mv monod-linux-amd64 /usr/local/bin/monod

# Verify
monod version

Build from Source​

Prerequisites​

# Install Go 1.24+
wget https://go.dev/dl/go1.24.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

# Verify
go version

Build​

# Clone repository
git clone https://github.com/mono-experimental/mono-core.git
cd mono-core

# Checkout release
git checkout <release-tag>

# Build
make build

# Install
sudo mv build/monod /usr/local/bin/

# Verify
monod version

Verify Installation​

# Check version
monod version

# Check available commands
monod --help

systemd Service Configuration​

systemd manages the monod process, ensuring it starts on boot and restarts on failure.

For standard deployments:

sudo tee /etc/systemd/system/monod.service > /dev/null <<EOF
[Unit]
Description=Monolythium Node
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=monod
Group=monod
WorkingDirectory=/home/monod
ExecStart=/usr/local/bin/monod start --home /home/monod/.monod

# Restart configuration
Restart=on-failure
RestartSec=3
StartLimitInterval=0

# Resource limits
LimitNOFILE=65535
LimitNPROC=4096

# Environment
Environment="HOME=/home/monod"

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/home/monod/.monod

[Install]
WantedBy=multi-user.target
EOF

Enable and Start Service​

# Reload systemd to pick up new unit file
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable monod

# Start service now
sudo systemctl start monod

# Check status
sudo systemctl status monod

# View logs
sudo journalctl -u monod -f

systemd Unit File Explained​

DirectivePurpose
User=monodRun as dedicated user (not root)
WorkingDirectory=/home/monodSet process working directory
ExecStart=...Command to start the node
Restart=on-failureAuto-restart on crashes
LimitNOFILE=65535Increase file descriptor limit
ProtectSystem=strictRead-only system directories
ReadWritePaths=/home/monod/.monodAllow writes only to data directory
Using Your User Account

If not using a dedicated monod user, replace:

  • User=monod with User=$USER
  • Group=monod with Group=$USER
  • /home/monod with $HOME

Service Management Commands​

# Start node
sudo systemctl start monod

# Stop node
sudo systemctl stop monod

# Restart node
sudo systemctl restart monod

# Check status
sudo systemctl status monod

# Enable auto-start on boot
sudo systemctl enable monod

# Disable auto-start
sudo systemctl disable monod

# View logs (last 100 lines)
sudo journalctl -u monod -n 100

# Follow logs in real-time
sudo journalctl -u monod -f

# View logs since last boot
sudo journalctl -u monod -b

Verify Checksums​

Always verify binary checksums:

# Download checksum file
curl -LO https://github.com/mono-experimental/mono-core/releases/download/${LATEST}/checksums.txt

# Verify
sha256sum -c checksums.txt --ignore-missing

Updating​

Manual Update​

# Stop service
sudo systemctl stop monod

# Download new binary
# ... (same as initial download)

# Start service
sudo systemctl start monod

Troubleshooting​

Permission Denied​

Symptom: bash: /usr/local/bin/monod: Permission denied

Solution:

# Make binary executable
chmod +x /usr/local/bin/monod

# Verify permissions
ls -l /usr/local/bin/monod
# Should show: -rwxr-xr-x

Command Not Found​

Symptom: monod: command not found

Solution:

# Check if binary exists
ls -l /usr/local/bin/monod

# Check PATH
echo $PATH

# Find monod
which monod

# If not in PATH, add to ~/.bashrc
echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc
source ~/.bashrc

Wrong Architecture​

Symptom: cannot execute binary file: Exec format error

Solution:

# Check your architecture
uname -m
# x86_64 = amd64
# aarch64 = arm64

# Verify binary architecture
file /usr/local/bin/monod
# Expected: ELF 64-bit LSB executable, x86-64

# Download correct binary for your architecture

systemd Service Fails to Start​

Symptom: systemctl status monod shows "failed" or "inactive (dead)"

Solution:

# Check detailed status
sudo systemctl status monod

# View recent logs
sudo journalctl -u monod -n 50 --no-pager

# Common issues:
# 1. Wrong user - verify User= matches existing user
# 2. Wrong home directory - verify paths exist
# 3. Binary not found - verify ExecStart= path is correct

# Test command manually
sudo -u monod /usr/local/bin/monod start --home /home/monod/.monod

Permission Issues with Data Directory​

Symptom: permission denied errors in logs when accessing ~/.monod/

Solution:

# Fix ownership (if using dedicated user)
sudo chown -R monod:monod /home/monod/.monod

# Fix permissions
sudo chmod 700 /home/monod/.monod
sudo chmod 600 /home/monod/.monod/config/priv_validator_key.json
sudo chmod 600 /home/monod/.monod/config/node_key.json

# Verify
sudo -u monod ls -la /home/monod/.monod/config/

Port Already in Use​

Symptom: bind: address already in use

Solution:

# Find process using port 26656 (or other ports)
sudo lsof -i :26656

# Kill conflicting process (if safe)
sudo kill <PID>

# Or change port in config.toml
vim ~/.monod/config/config.toml
# Find: laddr = "tcp://0.0.0.0:26656"
# Change to: laddr = "tcp://0.0.0.0:26666"

Out of Disk Space​

Symptom: no space left on device

Solution:

# Check disk usage
df -h

# Check monod directory size
du -sh ~/.monod/data

# Prune old data (if running archive node)
# WARNING: This removes historical state
monod prune --home ~/.monod

# Or increase disk size (recommended)

Sync Stuck or Very Slow​

Symptom: Node syncing slowly or stuck at specific height

Solution:

# Check peer count
curl localhost:26657/net_info | jq '.result.n_peers'
# Should be > 5 for good sync performance

# Update peers
monarch peers update --network Testnet

# Restart to pick up new peers
sudo systemctl restart monod

# Consider using state-sync instead
# See: https://docs.monolythium.com/operators/state-sync

SELinux Blocking Access (RHEL/CentOS)​

Symptom: Permission errors despite correct ownership/permissions

Solution:

# Check SELinux status
getenforce

# Temporarily set to permissive (for testing)
sudo setenforce 0

# Permanently disable (if needed)
sudo vim /etc/selinux/config
# Set: SELINUX=permissive

# Or configure proper SELinux policies (recommended)

Next Steps​

After successful installation: