Compile and Run without Container

(12 nL)
👍Tip 2 nL
To Share and +4 nLEARNs

This doc is written for developers, sysadmins, DevOps, or curious people who want to know how to compile and run a regular NEAR validator node natively (without containerization) for one of the following networks:

Prerequisites

  • Rust. If not already installed, please follow these instructions.
  • Git
  • Installed developer tools:
    • MacOS 
      $ brew install cmake protobuf clang llvm
    • Linux 
      $ apt update
$ apt install -y git binutils-dev libcurl4-openssl-dev zlib1g-dev libdw-dev libiberty-dev cmake gcc g++ python docker.io protobuf-compiler libssl-dev pkg-config clang llvm

How to use this document

This document is separated into sections by network ID. Although all of the sections have almost the exact same steps/text, we found it more helpful to create individual sections so you can easily copy-paste commands to quickly get your node running.

Choosing your nearcore version

When building your NEAR node you will have two branch options to choose from depending on your desired use:

  • master : (Experimental)
    • Use this if you want to play around with the latest code and experiment. This branch is not guaranteed to be in a fully working state and there is absolutely no guarantee it will be compatible with the current state of mainnet or testnet.
  • Latest stable release : (Stable)
    • Use this if you want to run a NEAR node for mainnet. For mainnet, please use the latest stable release. This version is used by mainnet validators and other nodes and is fully compatible with the current state of mainnet.
  • Latest release candidates : (Release Candidates)
    • Use this if you want to run a NEAR node for tesnet. For testnet, we first release a RC version and then later make that release stable. For testnet, please run the latest RC version.

(Optional) Enable debug logging

Note: Feel free to skip this step unless you need more information to debug an issue.

To enable debug logging, run neard like this:

$ RUST_LOG=debug,actix_web=info ./target/release/neard --home ~/.near run

localnet

1. Clone nearcore project from GitHub

First, clone the nearcore repository.

$ git clone https://github.com/near/nearcore

Next, checkout the release branch you need if you will not be using the default master branch. [ More info ]

$ git checkout master

2. Compile nearcore binary

In the repository run the following commands:

$ make neard

This will start the compilation process. It will take some time
depending on your machine power (e.g. i9 8-core CPU, 32 GB RAM, SSD
takes approximately 25 minutes). Note that compilation will need over
1 GB of memory per virtual core the machine has. If the build fails
with processes being killed, you might want to try reducing number of
parallel jobs, for example: CARGO_BUILD_JOBS=8 make neard.

By the way, if you’re familiar with Cargo, you could wonder why not
run cargo build -p neard --release instead. While this will produce
a binary, the result will be a less optimized version. On technical
level, this is because building via make neard enables link-time
optimisation which is disabled by default. The binary path is target/release/neard.

For localnet, you also have the option to build in nightly mode (which is experimental and is used for cutting-edge testing). When you compile, use the following command:

$ cargo build --package neard --features nightly_protocol,nightly_protocol_features --release

3. Initialize working directory

In order to work properly, the NEAR node requires a working directory and a couple of configuration files.

  • config.json – Configuration parameters which are responsive for how the node will work.
  • genesis.json – A file with all the data the network started with at genesis. This contains initial accounts, contracts, access keys, and other records which represents the initial state of the blockchain.
  • node_key.json – A file which contains a public and private key for the node. Also includes an optional account_id parameter which is required to run a validator node (not covered in this doc).
  • data/ – A folder in which a NEAR node will write its state.
  • validator_key.json – A file which contains a public and private key for local test.near account which belongs to the only local network validator.

Generate the initial required working directory by running:

$ ./target/release/neard --home ~/.near init --chain-id localnet

You can skip the --home argument if you are fine with the default working directory in ~/.near. If not, pass your preferred location.

This command will create the required directory structure and will generate config.json, node_key.json, validator_key.json, and genesis.json for localnet network.

4. Run the node

To run your node, simply run the following command:

$ ./target/release/neard --home ~/.near run

That’s all. The node is running you can see log outputs in your console.

testnet

1. Clone nearcore project from GitHub

First, clone the nearcore repository.

$ git clone https://github.com/near/nearcore
$ git fetch origin --tags

Checkout to the branch you need if not master (default). Latest release is recommended. Please check the releases page on GitHub. Current latest is 1.20.0

$ git checkout tags/1.20.0 -b mynode

2. Compile nearcore binary

In the nearcore folder run the following commands:

$ make neard

This will start the compilation process. It will take some time
depending on your machine power (e.g. i9 8-core CPU, 32 GB RAM, SSD
takes approximately 25 minutes). Note that compilation will need over
1 GB of memory per virtual core the machine has. If the build fails
with processes being killed, you might want to try reducing number of
parallel jobs, for example: CARGO_BUILD_JOBS=8 make neard.

By the way, if you’re familiar with Cargo, you could wonder why not
run cargo build -p neard --release instead. While this will produce
a binary, the result will be a less optimized version. On technical
level, this is because building via make neard enables link-time
optimisation which is disabled by default.

The binary path is target/release/neard

3. Initialize working directory

In order to work properly, the NEAR node requires a working directory and a couple of configuration files.

  • config.json – Configuration parameters which are responsive for how the node will work.
  • genesis.json – A file with all the data the network started with at genesis. This contains initial accounts, contracts, access keys, and other records which represents the initial state of the blockchain.
  • node_key.json – A file which contains a public and private key for the node. Also includes an optional account_id parameter which is required to run a validator node (not covered in this doc).
  • data/ – A folder in which a NEAR node will write it’s state.

Generate the initial required working directory by running:

$ ./target/release/neard --home ~/.near init --chain-id testnet --download-genesis

You can skip the --home argument if you are fine with the default working directory in ~/.near. If not, pass your preferred location.

This command will create the required directory structure and will generate config.json, node_key.json, and genesis.json for testnet network.

Heads up
The genesis file for testnet is big (6GB +) so this command will be running for a while and no progress will be shown.

4. Replacing the config.json

The generated config.json will be missing a boot_nodes parameter (it is empty) so we will need to replace it with a full one. You can do this one of two ways:

  1. Download config.json here and replace it in your working dir (~/.near/config.json).

or

  1. Run the following commands:
$ rm ~/.near/config.json
$ wget -O ~/.near/config.json https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/testnet/config.json

5. Get data backup

The node is ready to be started however you must first sync up with the network. This means your node needs to download all the headers and blocks that other nodes in the network already have. You can speed up this process by downloading backups in one of two ways:

  1. Download and unpack the tar file to ~/.near.

or

  1. Run the following commands:
$ wget -O ~/.near/data.tar https://near-protocol-public.s3.ca-central-1.amazonaws.com/backups/testnet/rpc/data.tar
$ mkdir -p ~/.near/data
$ tar -xf ~/.near/data.tar -C ~/.near/data
$ rm ~/.near/data.tar

NOTE: The .tar file is ~32GB (and will grow) so make sure you have enough disk space to unpack inside the data folder.

6. Run the node

To start your node simply run the following command:

$ ./target/release/neard --home ~/.near run

That’s all. The node is running you can see log outputs in your console. It will download a bit of missing data since the last backup was performed but it shouldn’t take much time.

mainnet

1. Clone nearcore project from GitHub

First, clone the nearcore repository.

$ git clone https://github.com/near/nearcore
$ git fetch origin --tags

Next, checkout the release branch you need (recommended) if you will not be using the default master branch. Please check the releases page on GitHub for the latest release.

For more information on choosing between master and latest release branch [ click here ].

$ git checkout tags/1.20.0 -b mynode

2. Compile nearcore binary

In the nearcore folder run the following commands:

$ make neard

This will start the compilation process. It will take some time
depending on your machine power (e.g. i9 8-core CPU, 32 GB RAM, SSD
takes approximately 25 minutes). Note that compilation will need over
1 GB of memory per virtual core the machine has. If the build fails
with processes being killed, you might want to try reducing number of
parallel jobs, for example: CARGO_BUILD_JOBS=8 make neard.

By the way, if you’re familiar with Cargo, you could wonder why not
run cargo build -p neard --release instead. While this will produce
a binary, the result will be a less optimized version. On technical
level, this is because building via make neard enables link-time
optimisation which is disabled by default.

The binary path is target/release/neard

3. Initialize working directory

In order to work NEAR node requires to have working directory and a couple of configuration files.

  • config.json – Configuration parameters which are responsive for how the node will work.
  • genesis.json – A file with all the data the network started with at genesis. This contains initial accounts, contracts, access keys, and other records which represents the initial state of the blockchain.
  • node_key.json – A file which contains a public and private key for the node. Also includes an optional account_id parameter which is required to run a validator node (not covered in this doc).
  • data/ – A folder in which a NEAR node will write it’s state.

Generate the initial required working directory by running:

$ ./target/release/neard --home ~/.near init --chain-id mainnet

You can skip the --home argument if you are fine with the default working directory in ~/.near. If not, pass your preferred location.

This command will create the required directory structure by generating a config.json, node_key.json, and downloads a genesis.json for mainnet.

4. Replacing the config.json

The generated config.json will be missing a boot_nodes parameter (it is empty) so we will need to replace it with a full one. You can do this one of two ways:

  1. Download config.json here and replace it in your working dir (~/.near/config.json).

or

  1. Run the following commands:
$ rm ~/.near/config.json
$ wget -O ~/.near/config.json https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/mainnet/config.json

5. Get data backup

The node is ready to be started however the first thing you need to do is to sync up with the network. This means your node needs to download all of the headers and blocks that other nodes on the network have. This process can be sped up drastically by downloading backups one of two ways:

  1. Download and unpack the tar file to ~/.near.

or

  1. Run the following commands:
$ wget -O ~/.near/data.tar https://near-protocol-public.s3.ca-central-1.amazonaws.com/backups/mainnet/rpc/data.tar
$ mkdir -p ~/.near/data
$ tar -xf ~/.near/data.tar -C ~/.near/data
$ rm ~/.near/data.tar

NOTE: The .tar file is ~125GB (and will grow) so make sure you have enough disk space to unpack inside the data folder.

6. Run the node

To start your node simply run the following command:

$ ./target/release/neard --home ~/.near run

That’s all. The node is running and you can see log outputs in your console. It will download a bit of missing data since the last backup was performed but it shouldn’t take much time.

Got a question?

Ask it on StackOverflow!

Generate comment with AI 2 nL
Scroll to Top
Report a bug👀