Installing from Source

A step-by-step guide on how to prepare a fully-functional environment from source.

If you don't have access to a Linux box you can quickly setup one on DigitalOcean and other cloud providers.

Introduction

This guide will take you through the basic steps of setting up a development environment from scratch on a fresh Linux (*.deb based) box. We officially recommend and support Ubuntu operating system.

Step 1: User setup

We will create a new user mainsail and add this user to the sudoers group (allowing root execution if needed). You can skip this step as a developer and continue to next steps below.

If you are running on a fresh cloud box, like for example DigitalOcean, then create a user with the following commands below.

# Create the user (example: 'mainsail')
sudo adduser mainsail
sudo usermod -aG sudo mainsail

# Login as the newly user
sudo su - mainsail

Step 2: Update the System

Before we start, we need to make sure that the system is up to date. This can be done by running the following commands.

sudo apt-get update
sudo apt-get upgrade -y

Step 3: Install Essential Packages

The command below installs the necessary packages that are required by Mainsail or related scripts.

sudo apt-get install -yq git curl apt-transport-https build-essential python-is-python3 python3-setuptools libjemalloc-dev pkg-config libtool autoconf automake

This guide targets Ubuntu 22.04+, where Python 3 (python3) is installed by default. Some native build tools (like node-gyp) may expect the python command to be available. This guide already installs python-is-python3, which ensures python points to Python 3.

Step 4: Install NVM & Node.js Runtime

Mainsail is written exclusively in Node.js, the server-side framework for JavaScript, Typescript, installing Node.js is a necessity for Mainsail development. The code below installs NVM - Node Version Manager, which allows you to install and manage multiple versions of Node.js on the same system.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Now that NVM is installed, you can install the latest version of Node.js. The following command will install the latest LTS version of Node.js.

nvm install --lts

Step 5: Install Rustup & Rust

This installs the latest stable version of Rust via rustup, the official Rust toolchain manager.

# 1. Download and run the official rustup installer
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. Follow the prompts (press enter to proceed with default settings)

# 3. Restart your shell (or run the following to load Rust immediately)
source "$HOME/.cargo/env"

# 4. Confirm Rust is installed and check version
rustc --version

Step 6: Install PNPM Package Manager

Pnpm is a package manager for JavaScript, which is fast, disk space efficient, and optimized for monorepos. It uses hard links and symlinks to save one version of a module only ever once on a disk. This is especially useful for a monorepo like Mainsail.

npm install -g npm@latest
npm i -g pnpm

pnpm setup

Step 7: Clone The Mainsail Repository

Let's clone our Mainsail repository and run the initial pnpm run setup command.

pnpm run setup command leverages Lerna to clean, bootstrap and build the Mainsail packages (including transpiling typescript). For mode information look into project package.json file in the root folder.

git clone https://github.com/ArkEcosystem/mainsail
cd mainsail
pnpm run setup  #run Lerna to clean, bootstrap and build packages

The build process can take a while, especially during the @mainsail/evm:build step. If any required system dependencies are missing (such as Rust or Python), errors will be shown at that stage. Make sure these are installed and available in your environment to avoid build failures.

Step 8: Run network

Step 8.1: Run local devnet

Now that we have the Mainsail repository cloned and setup, we can run a local devnet network. The local devnet network is a local blockchain network that is used for development and testing purposes. The local network will not be able to connect to the mainnet or testnet, but it will allow you to test your plugins and dApps in a controlled environment.

cd packages/core
pnpm run full:devnet

Step 8.2: Run official testnet

If you want to run the official testnet, you can use the following command.

cd packages/core

SNAP=$(curl -s -L -H "Accept: application/vnd.github+json" "https://api.github.com/repos/ArkEcosystem/mainsail-network-config/contents/testnet/mainsail/"  | grep  compressed | grep download_url | awk '{ print $2 }' | tr -d ",")
pnpm run mainsail config:publish:custom --app=https://raw.githubusercontent.com/ArkEcosystem/mainsail-network-config/main/testnet/mainsail/app.json --crypto=https://raw.githubusercontent.com/ArkEcosystem/mainsail-network-config/main/testnet/mainsail/crypto.json --peers=https://raw.githubusercontent.com/ArkEcosystem/mainsail-network-config/main/testnet/mainsail/peers.json --snapshot=${SNAP} --reset

pnpm run mainsail env:set --key=MAINSAIL_P2P_HOST --value=0.0.0.0 && \
pnpm run mainsail env:set --key=MAINSAIL_P2P_PORT --value=4000 && \
pnpm run mainsail env:set --key=MAINSAIL_API_TRANSACTION_POOL_HOST --value=0.0.0.0 && \
pnpm run mainsail env:set --key=MAINSAIL_API_TRANSACTION_POOL_PORT --value=4007 && \
pnpm run mainsail env:set --key=MAINSAIL_API_EVM_HOST --value=0.0.0.0 && \
pnpm run mainsail env:set --key=MAINSAIL_API_EVM_PORT --value=4008

pnpm run mainsail core:run