A Step-by-Step Guide to Managing and Deploying Celo Node


Celo is a robust blockchain platform that offers a decentralized financial ecosystem that is secure, transparent, and accessible to anyone with a smartphone. In this beginner-friendly guide, we will walk you through the step-by-step process of deploying and managing a Celo node that connects to the Celo network. In a previous tutorial, we have seen how to deploy a Celo node using typescript from the Celo monorepo. However, this tutorial will be more detailed as it introduces you to different kinds of the Celo Node and the indifferent ways they differ from each other. Furthermore, by the end of the tutorial, we will be deploying a simple node that uses javascript to call the Celo api on the Alfajores network.


To complete this tutorial, you will need:

  1. A Linux computer (such as Ubuntu 18.04 or higher).

  2. Basic command line information.

  3. Know JavaScript and Node.js.


An important point before you get started is that you need to have prior knowledge of the Celo ecosystem and/or other blockchain node systems. Inasmuch as this article is designed to be beginner friendly, a foundational knowledge of how the nodes work might help you understand this article better. Here is a learning resource to learn about blockchain nodes.

Picking a Node

In the blockchain ecosystem, there are several types of nodes that a stakeholder can run to contribute to the stability of the network. However, in the Celo system there are two prominent types of nodes you can choose from. These types are the light node and the full node.

Celo Full Node

A Celo full node downloads and runs the entire Celo blockchain on your device. This makes full nodes more expensive when compared to other kinds of node, but they offer a number of advantages, including:

  • Increased security: Full nodes can verify all transactions on the blockchain, which helps to prevent fraud and other malicious activity.

  • Increased decentralization: Full nodes are more decentralized than light nodes, which makes the Celo network more resilient to attack.

  • Increased participation: Full nodes allow users to participate in the Celo network by validating transactions and earning rewards.

Should you be interested in running a full node, here are what you will need:

  • A computer with at least 8GB of RAM

  • An internet connection with at least 10Mbps download speed

  • At least 100GB of storage space

  • Decide which network you want to use and how to install it

Once you have installed the necessary tools, you will need to configure it with your Celo wallet address and password. Now you can then start syncing the blockchain to your device. Note, this might take a lot of time to boot up, but as long as you have a strong internet connection, it will download successfully.

However, there are some additional conditions for running a Celo full node which includes:

  • It is strongly advised to perform this operation on a Linux operating system.

  • You must have a static IP address.

  • The node needs to be online 24/7.

The Celo Monorepo or the Celo website is a great place to find additional information about how to run a Full Celo Node.

Celo Light Node

This is a node that does not download the entire blockchain information on your device. Instead, it connects to a full node and requests the information that it needs. This method makes the light nodes much more lightweight than full nodes, and they can be run on devices with limited storage capacity or a machine with slower internet connections to the full node requirement.

To run a Celo light node, you will need:

  • A computer with at least 4GB of RAM

  • An internet connection

  • Celo network accessibility for deployment

Once you have installed the software, you will need to configure it with your Celo wallet address and password. You can then connect to a full node and start using your light node to interact with the Celo blockchain. The monorepo is also a way you can use to connect to the Celo full node, you just need to specify the parameter during installation. To begin, simply clone the Celo monorepo and build the files. You can check the Celo documentation for additional information.

Hosted Nodes

Another type of node you may want to know about is the Celo node hosted by a third-party provider. This means you can connect to a provider-managed site instead of running your own node.

However, doing this has a number of benefits such as:

  • Ease of use: You do not need to worry about setting up or maintaining your own node.

  • Cost-effective: Hosted nodes are often more expensive than running your own nodes.

  • Scalability: Control nodes can be scaled to meet the needs of the application.

However, this comes with some disadvantages too, such as:

  • Security: You may have less control over the security of your data if it is hosted by a third party.

  • Compliance: You may need to comply with the terms of service of the hosted node provider.

Overall, hosted nodes can be a good option for users who want to simplify their node management and reduce costs. However, it is important to weigh the benefits and drawbacks before deciding whether or not to use a hosted node.

Here are some of the providers that offer hosted Celo nodes:

  • cLabs: cLabs is the organization that created Celo. They offer a hosted node service that is designed for developers and businesses.

  • Forno: Forno is a cloud computing platform that offers a hosted node service for Celo.

  • Blockdaemon: Blockdaemon is a blockchain infrastructure provider that offers a hosted node service for Celo

Deploying a Node

For the purpose of this tutorial, we will be focusing on the light node that uses the Alfajores testnet. However, we will be using JavaScript to call the ethers library that connects us to Celo

Step 1: Set Up the Environment

First of all, let’s work on setting up the appropriate software and dependencies that will help us with the projects.

  1. The first place to start is by installing the Javascript framework; Node.js. This is because Celo nodes are built using Node.js, hence, to deploy our own Celo node as well, we need to use Node.js. There are several ways to install Node Js, one of these approaches is to use the Node.js official website. However, because we will be using the celocli, which requires using the version 12.0.0 specifically, hence, we will have to install Node using the Node Version Manager (NVM). To do that, let’s install NVM which will help us select the version we want. Here is a simple step to install NVM. Once you’re done installing NVM, we can then move on to install Node with the following commands:

nvm install node

Once Node installs successfully, we then move on to install the version 12 which we will be using to install celocli.

nvm install 12.0.0

You can check the node version it is currently using with this command:

node –version

If it returns an highlighted 12.0.0, then we are sure it is now using the version 12.0.0. Else, we can dictate which version to use by running the nvm use command:

nvm use 12.0.0

  1. Install Git: Git is a version control system. You can install it by following the instructions for your operating system from the official Git website. By default, git comes installed on most recent linux distros, to confirm you have git already installed, you can check by typing the command below:

git –version

This should return the version installed on your machine.

However, if the returned information suggests it is not installed, here is a command you can use to install git from the command line:

sudo apt-get install git

  1. Install the Celo CLI: The Celo Command Line Interface (CLI) is a tool that simplifies interactions with the Celo network. Open your terminal and run the following command:

npm install -g @celo/celocli

  1. Create a Celo account: everything you need to do on the Celo network will definitely require you to have a Celo account which you can connect. One easy way you can easily create an account is by using the celocli. To create an account, simply type the following command on the terminal:

celocli account:new

You should get a feedback that looks like the picture below, containing your mnemonic; private key; public key; and your Celo address.

Please note, this will not save anywhere, so you will need to write it somewhere safe or redirect the output to a file which you can then backup somewhere safe later. To redirect the output to another file on Linux, you can use the command

celocli account:new >> FILE_NAME

Step 2: Set Up the Node

Now that our environment is ready, let’s proceed to picking and set up our Celo node.

Celo supports a couple of deployment networks, including Alfajores (testnet) and Mainnet. For this tutorial, we will focus on Alfajores. The Alfajores testnet is used by developers for testing their dApp on the celo network without risking real money which might lead to loss. Hence, we will also be using the Alfajores network in the tutorial for learning purposes.

There are various ways we can connect a node to the Alfajores network for testing purposes. We will be showing the steps for using JavaScript that calls the ethers library.

  • Setting Up The Project

First, we need to create a new folder/directory for the project, let’s call this directory testNode.

mkdir testNode && cd testNode

This command will create the directory and move us into the directory. Next, we need to initialize node in the directory as follows:

npm init -y

The initialization process should now create a package.json file in the work directory. Now, let’s create a new file to save our codes.

touch index.js

  • Installing the Project Packages

At this point we need to install a package that helps us communicate with Celo directly by simply making an API call. For this project, the ethers and @celo-tools/celo-ethers-wrapper will be serving the function of connecting us to the Celo network.

So, go ahead and type the following command at the root of your project directory:

npm install ethers @celo-tools/celo-ethers-wrapper

The ethers package provides a JavaScript API that helps us interact with the Ethereum Blockchain, while the Celo package makes connecting to the Celo network a lot easier.

Before execution our directory should look like this:


But, after successful execution, the directory should now contain some new files that look like this


Here is also a snippet of what you should have inside the node module if it has installed properly:

  • Writing the JavaScript Code

Now, we can write the JavaScript Code by starting with a line that imports the ethers library:

const { ethers } = require('ethers');

async function deployLightNode() {
    const provider = new ethers.providers.JsonRpcProvider('https://alfajores-forno.celo-testnet.org');
    const privateKey = 'YOUR_PRIVATE_KEY'; // Replace with your account private key
    const wallet = new ethers.Wallet(privateKey, provider);
    const lightNodeFactory = await ethers.getContractFactory('LightNode');
    const lightNode = await lightNodeFactory.connect(wallet).deploy();

    console.log(`Light Node deployed at address: ${lightNode.address}`);


Here is an explanation of what each part of the code does:

It creates a function that first imports the ethers library, which provides a JavaScript API for interacting with the Ethereum blockchain.

The function then defines a few variables:

provider: A JSON-RPC provider that connects to the Celo testnet.

privateKey: A private key that is used to sign transactions.

wallet: A wallet object that is created from the private key.

lightNodeFactory: A contract factory that is used to deploy the Light Node contract.

lightNode: The deployed Light Node contract.

The function then deploys the Light Node contract by calling the connect() and deploy() methods on the lightNodeFactory object. The connect() method connects the contract factory to the wallet, and the deploy() method deploys the contract on the blockchain.

Finally, the function logs the address of the deployed Light Node contract.

To run the function, you will need to replace the YOUR_PRIVATE_KEY placeholder with your own private key. You can get your private key from the celocli account:new.

Note that we import ethers using destructuring syntax { ethers }. This is because the ethers library exports multiple modules, and we only need to import the main module for our code to work.

Step 3: Run the Celo Node

Now that our Celo node is set up, let’s run it:

Initialize the Node: Initialize your node by running the following command:

node index.js

This will start the node and synchronize it with the Celo network.

Step 4: Monitor and Manage the Node

Congratulations! Your Celo node is up and running. Let’s explore how to monitor and manage it

Once the Light Node contract has been deployed, you can manage it locally using the ethers library. The ethers library provides a number of methods for interacting with Light Node contracts using JavaScript. This includes:

getBalance(): Gets the balance of the Light Node contract.

sendTransaction(): Sends a transaction to the Light Node contract.

query(): Queries the Light Node contract for information.

To manage the Light Node contract, you will need to connect to the contract using the ethers library. You can do this by creating a wallet object and then connecting the wallet to the contract. Once you have connected to the contract, you can use the ethers library methods to interact with the contract.

For example, to get the balance of the Light Node contract, you would use the following code:

const lightNode = await ethers.getContract('LightNode', 'YOUR_CONTRACT_ADDRESS');
const balance = await lightNode.getBalance();
console.log(`The balance of the Light Node contract is: ${balance}`);

To send a transaction to the Light Node contract, you would use the following code:

const lightNode = await ethers.getContract('LightNode', 'YOUR_CONTRACT_ADDRESS');

const transaction = lightNode.sendTransaction({
    value: 1000000000000000000,

console.log(`The transaction to the Light Node contract has been sent`);

To query the Light Node contract for information, you would use the following code:

const lightNode = await ethers.getContract('LightNode', 'YOUR_CONTRACT_ADDRESS');
const information = await lightNode.query('information');
console.log(`The information from the Light Node contract is: ${information}`);

For more information on how to manage your Light Node contracts using the ethers library, please refer to the ethers documentation.


In this beginner-friendly guide, we walked through the step-by-step process of deploying and managing a Celo node. By following these instructions, you should now have a functioning Celo node up and running on the Alfajores testnet. Remember to continuously monitor your node’s status, update your validator metadata, and stay engaged with the Celo community to maximize your participation in the network.

Blockchain technology has the potential to transform the global financial landscape, and Celo is at the forefront of this revolution. By becoming a Celo node operator, you contribute to a more inclusive and transparent financial system. Embrace this opportunity to learn, experiment, and be part of the decentralized future.

Happy nodemanship on Celo!

Disclaimer: This article is a beginner-friendly guide and should not be considered financial or investment advice. Make sure you understand all the risk involved in participating in a blockchain process especially in a node process before staking your money.

Next Steps

Now that your node is up and running, another area you should read more on is how to become a Celo validator which will allow you to participate in validating transactions and adding them to the blockchain, ensuring the network’s security and reliability.

I’ll be writing another article soon to help you debug issues while building on the Celo Blockchain. Till then, you can keep learning more about Celo from the Celo Documentation…

About the Author​

‘Tobi Olajide is an enthusiastic writer interested in blockchain technology and has been writing about it for over 3 years. He is also a software engineer with over 2 years of experience. You can connect with him on twitter, linkedln, or github to learn more about his programming journey.


1 Like

Approved for you to get started. You can manage the tutorial here by changing the category to Proposals > In Progress then Proposals > Review as you complete the tutorial. Thanks!

i will review this

1 Like

alright, i’ll be looking forward to hearing from you.

hi @yafiabiyyu , I’ve added the corrections as suggested.

Hi @joenyzio can you kindly look into this?