Installing from Source

A step-by-step guide on how to prepare a fully-functional environment from source on your local machine. Note that we also have a guide for Docker setup if you prefer that method.

Introduction

This guide will take you through the basic steps of setting up a development environment from scratch on your local machine. The instructions are for unix systems (Linux and macOS). Windows users are encouraged to use WSL2 with a Ubuntu distribution.

Prerequisites

Before starting the local setup process, ensure that you have the following software and versions installed on your machine:

Installation of these packages will differ based on your operating system. Please refer to the official documentation of each software for installation instructions.

For Linux users, the following additional steps are necessary to install required build tools and libraries:

sudo apt-get install build-essential python-is-python3 libjemalloc-dev -yq

Mainsail Setup

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
git checkout develop # or any other branch you want to work on
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.

Configure & Run Local Network

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.

Before starting the network, have a look at the .env file located in packages/core/bin/config/devnet/core and adjust the settings to your needs. You can find a full overview of the Mainsail environment variables here, but we'll highlight some of the most important ones for local development:

MAINSAIL_API_SYNC_ENABLED=true # To enable the API sync feature which stores data in the Postgres database

# Configure the database to your needs
MAINSAIL_DB_DATABASE=test_db
MAINSAIL_DB_USERNAME=test_db
MAINSAIL_DB_PASSWORD=password

In order to make the REST API work, you will also need to adjust the app.json file in packages/core/bin/config/devnet/core. Open the file and add the @mainsail/http-api package as follows:

...,
{
  "package": "@mainsail/api-development"
},
{
  "package": "@mainsail/api-http"
},
{
  "package": "@mainsail/webhooks"
},
...

After adjusting the configuration, you can start the local devnet network with the following command:

cd packages/core # from mainsail root folder
pnpm run full:devnet

Troubleshooting

If you encounter any issues during the setup of Mainsail, pay close attention to the errors you encounter. The stack trace often provides enough details to identify the step it's failing on (e.g., missing dependencies, build errors, etc.).

In case you notice errors while starting the local devnet network, try running pnpm run mainsail env:paths:clear --data from the packages/core folder to clear any cached paths and data. This can help resolve issues related to corrupted or outdated data, especially if you have fetched new changes from the repository.