Skip to main content

Run a Node on Linux and MacOS

This doc is written for developers, sysadmins, DevOps, or curious people who want to know how to run a NEAR node using nearup on Linux and MacOS, with or without using Docker.

nearup Installation#

You can install nearup by following the instructions at https://github.com/near/nearup.

Heads up

The README for nearup (linked above) may be all you need to get a node up and running in testnet and localnet. nearup is exclusively used to launch NEAR testnet and localnet nodes. nearup is not used to launch mainnet nodes. See Deploy Node on Mainnet for running a node on mainnet.

The steps in the rest of this document will require nearup

Running a Node using Docker#

Install Docker#

By default we use Docker to run the client.

Follow these instructions to install Docker on your machine:

Running nearup with Docker#

Note: `nearup` and `neard` are running inside the container. You have to mount the ~/.near folder to ensure you don't lose your data which should live on the host.

Once nearup and Docker are installed (by following instructions in previous section), run:

docker run -v $HOME/.near:/root/.near -p 3030:3030 --name nearup nearprotocol/nearup run testnet

(If you prefer to use localnet then just replace testnet with localnet in the command above)

You will then be prompted for an Account ID. You can leave this empty if you would just like to run a node. Validators should use the account ID of the account you want to stake with. See staking if you would like to become a validator.

Enter your account ID (leave empty if not going to be a validator):

Running in detached mode#

To run nearup in docker's detached (non-blocking) mode, you can add -d to the docker run command,

docker run -v $HOME/.near:/root/.near -p 3030:3030 -d --name nearup nearprotocol/nearup run testnet

Execute nearup commands in container#

To execute other nearup commands like logs, stop, run, you can use docker exec,

docker exec nearup nearup logsdocker exec nearup nearup stopdocker exec nearup nearup run {testnet/localnet}

(The container is running in a busy wait loop, so the container won't die.)

nearup logs#

To get the neard logs run:

docker exec nearup nearup logs

or,

docker exec nearup nearup logs --follow

To get the nearup logs run:

docker logs -f nearup

text-alt

Legend
# 7153BlockHeight
V/1V (validator) or (regular node) / Total Validators
0/0/40connected peers / up to date peers / max peers

Compiling and Running a Node without Docker#

Alternatively, you can build and run a node without Docker by compiling neard locally and pointing nearup to the compiled binaries. Steps in this section provide details of how to do this.

For Mac OS, make sure you have developer tools installed and then use brew to install extra tools:

brew install cmake protobuf clang llvm

For Linux, install these dependencies:

apt updateapt 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

Then clone the repo:

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

Checkout the version you wish to build:

git checkout <version>

You can then run:

make neard

This will compile the neard binary for the version you have checked out, it will be available under target/release/neard.

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.

NB. Please ensure you build releases through make rather than cargo build --release. The latter skips some optimisations (most notably link-time optimisation) and thus produces a less efficient executable.

Finally: On MacOS or Linux

nearup run testnet --binary-path path/to/nearcore/target/release

If you want to run localnet instead of testnet, then replace testnet with localnet in the command above.

You will then be prompted for an Account ID. You can leave this empty if you would just like to run a node. Validators should use the account ID of the account you want to stake with. See staking if you would like to become a validator.

Enter your account ID (leave empty if not going to be a validator):

Running a Node on GCP#

Create a new instance, following the Hardware requirements.

Add firewall rules to allow traffic to 24567 port from all IPs (0.0.0.0/0)

SSH into the machine (there is "SSH" button in the console or use gcloud ssh command) and run:

sudo apt updatesudo 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

Success Message#

Once you have followed the steps for running a node with Docker or of Compiling without Docker, you should see messages similar to as shown below:

Using local binary at path/to/nearcore/target/releaseOur genesis version is up to dateStarting NEAR client...Node is running!To check logs call: `nearup logs` or `nearup logs --follow`

or

Using local binary at path/to/nearcore/target/releaseOur genesis version is up to dateStake for user 'stakingpool.youraccount.testnet' with 'ed25519:6ftve9gm5dKL7xnFNbKDNxZXkiYL2cheTQtcEmmLLaW'Starting NEAR client...Node is running!To check logs call: `nearup logs` or `nearup logs --follow`

Starting a node from backup#

Using data backups allows you to sync your node quickly by using public tar backup files. There are two types of backups for available for both testnet and mainnet:

  • regular
  • archival

Archive links#

mainnet

testnet

Starting node using neard backup data

./neard init --chain-id <chain-id> --download-genesiscd ~/.near/datawget <link-above>tar -xf data.tarrm data.tar./neard run

Starting node using nearup backup data:

nearup run <chain-id> && sleep 30 && nearup stopcd ~/.near/<chain-id>/datarm ./* # clean up old DB files to avoid corruptionwget <link-above>tar -xf data.tarrm data.tarnearup run <chain-id> 

( <chain-id> corresponds to testnet or mainnet )

Note: Default location for neard data is ~/.near/data. nearup stores data by default in ~/.near/<chain-id>/data.

Got a question?

Ask it on StackOverflow!