Run an Ergo Full Node at Home

Guess who’s back?

To follow up on my Cardano Node at Home guide, I’ve decided to write up the process I used to set up an Ergo full node on an Ubuntu VM here in my home lab. Using this guide below, you can run your own non-mining Ergo full node on a spare PC or a VM at home.

As with the Cardano guide, this guide assumes your node will be run on a home network, behind a firewall. Please do not use this guide to build a machine with a public IP address, I’m not covering essential security guidelines for internet-facing hosts; if you don’t know what you’re doing, you’re going to have a bad time.

Quick Note
If you’ve already built a Cardano node using the Cardano Node at Home guide, I recommend using a separate computer or VM for this guide. Unless your PC or VM has 4-8 fast cores and 32GB+ RAM, I don’t recommend running both nodes on the same system.

Part 1: Install Ubuntu Linux on a Spare PC or a VM

The first step to setting up your Ergo node is to install Ubuntu Linux on your PC or VM.

This part is identical to the process I used for building the Cardano node, so I’m going to link you to that post.

While you’re running through the post linked below, you’ll see a number of references to “Cardano,” as that’s what I originally wrote the guide for. Feel free to replace any occurrence of the word “cardano” with “ergo.” For example, instead of cardano01 for the hostname, I used ergo01 when I set up my Ergo node’s VM.

Head over to Part 1 of the Cardano Node at Home guide, and when you’re done with that, come back to this post and continue with Part 2.

Part 2: Configuring the Ergo Node

Welcome back! I hope your Ubuntu install went well. If you ran into trouble, ping me on Twitter (@brav0charlie) and I’ll do what I can to give you a hand.

Now that you’ve got a working Ubuntu system with Docker installed, let’s get started installing our Ergo node!

I used the official ErgoDocs to set up my node, but I stumbled a few times with the setup, so I’ll clear all that up in the guide below.

Setting Up the Ergo Node using Docker

First, get logged into your host via SSH or the console.

Once you’re logged in, let’s start by creating a new directory called docker with a subdirectory named docker-ergo-node, and then we’ll change into that subdirectory:

mkdir docker/docker-ergo-node
cd docker/docker-ergo-node

The container will store it’s data in a hidden directory inside this directory. We must first create this directory, and then assign the correct ownership so the container will have access to this directory:

mkdir .ergo
chown -R 9052:9052 .ergo

The first command above creates the .ergo directory. I noted earlier that it’s a hidden directory—linux-based operating systems treat any file or directory that begins with a dot as a hidden item. The second command, chown, short for change ownership, does exactly that. The -R flag means recursive (applies to items inside .ergo as well as to the directory itself), and 9052:9052 refers to the User and Group IDs we’re granting access to.

Now that we’ve created our data directory and set ownership, we’re ready to create the Docker Compose file for our node. To do this, we’re going to use the nano editor:

nano docker-compose.yml

Once you’re in the nano editor, paste in the code below:

services:
  # Ergo blockchain node
  node:
    image: ergoplatform/ergo
    container_name: node
    hostname: node
    command: --mainnet -c /etc/ergo.conf
    volumes:
      - ./.ergo:/home/ergo/.ergo
      - ./ergo.conf:/etc/ergo.conf:ro
    ports:
      - 9053:9053
      - 9030:9030
    restart: unless-stopped
    # Increase or decrease the max heap value as required
    environment:
        - MAX_HEAP=4G
    logging:
      options:
        max-size: "10m"
        max-file: "3"

Once you’ve pasted in the above code, hit Ctrl-X to exit, Y to save, and Enter to confirm.

Now we’ll create our ergo.conf base configuration:

nano ergo.conf

Once you’re in the nano editor, paste in the following code:

ergo {
  node {
    mining = false
    }
  }
}

Once you’ve pasted in the above code, hit Ctrl-X to exit, Y to save, and Enter to confirm.

Starting the Node

Now we’re ready to start our node!

To start the node, use the the command below:

docker compose up -d

The command above instructs docker to start the stack defined in docker-compose.yml, and the -d flag means “detach.” This is what tells the container to run as a service in the background.

Part 3: Monitoring & Accessing the Node

The node will take quite some time to sync, think in terms of many hours. To monitor the node’s progress, you can use the docker logs facility to view the container’s logs, and you can use the integrated dashboard.

To view the docker container logs, use:

docker logs -f node

This tells docker, “show me the logs for the container named node,” and the -f flag means “follow.” This just means that logging data will be written live to the screen until you hit Ctrl-C to exit.

You can also view the integrated web dashboard by pointing the web browser on your desktop or laptop at the node.

The dashboard will be accessible at http://hostname:9053/panel. You’ll need to replace hostname with the hostname or the IP address of your node host, for example, ergo01 or 192.168.0.143.

If you do not know the IP address of your host, you can log into the host and type hostname -I at the command line and hit enter. The response will be a handful of IP addresses—the first address in that list should be your host’s IP address.

In the screenshot above, you’ll see that as I’m writing this guide, my node is already fully synced. When your node is still syncing, the Synchronization state and Sync progress fields will show your current sync progress.

Configuring the API Key

You’ll notice above that there’s a button at the top that says “Set API key.” Currently, we’re using the default, insecure key that was assigned. We want to change this so nobody without authorization may control our node.

First, choose a secure password, something 16+ characters. Keep that password in mind. This will be your “API Key.”

Get a Blake2b Hash of Your API key

Now, let’s head over to our Dashboard portal (see previous section). You’ll see a link on the left that says Swagger. Click that link, and then scroll down to the utils section:

From here, click the item that says /utils/hash/blake2b and it will expand to look like the screenshot below.

Now, click the Try it out button in the upper right of this section.

Replace the example string below (red box) with your API key we talked about above. Leave the quotes in place. If your password is password12345, you’d enter ”password12345”. Now click the Execute button.

Once you’ve hit execute, the lower part of the section will change:

In the screenshot above, you’ll see Responses. The field labeled Response body is your API Key Hash.

Copy this and save it somewhere safe, along with your API Key/password.

Add the API Key to ergo.conf

Now lets log into our node and change to the project directory and stop our Ergo node:

cd docker/docker-ergo-node
docker compose down

Now we can safely edit our ergo.conf file. To edit the ergo.conf file, we’ll use nano:

nano ergo.conf

Scroll all the way to the end of the file with your arrow keys or page down key, and you’ll see a section similar to the screenshot below.

You’ll notice I highlighted the line beginning with apiKeyHash. You’ll want to replace the string inside the quotes on this line with your API key hash. IMPORTANT: This is the hash you obtained in the previous step, not the “API Key”. Make sure you leave the quotes in place; your hash must be enclosed in quotes as shown above.

Once you’ve replaced the API key hash with your own, hit Ctrl-X to exit, Y to save, and Enter to confirm.

Now, let’s start our node back up:

docker compose up -d

Give the node about 30 seconds to initialize and then you’ll be able to access the Dashboard again.

To get to the dashboard, you’ll point your web browser at http://hostname:9053/panel, replacing hostname with the host name or IP address of your node.

Click the Set API Key button in the top left of the dashboard, and then paste in your API Key:

I’ve obscured my API key in the screenshot above, but once you’ve pasted in your API key, hit Save changes and you should see a message in the top right indicating the key was successfully set.

You’ll need to enter your API key with each new session established with your node’s dashboard. Think of this as a login to the node that grants you management privileges on the node.

Closing Thoughts

Once your node is fully synced, you can create and attach a new hot-wallet for the node, so you can perform transactions using your node. I recommend creating a new, separate wallet and treating it as a hot wallet. Keep your Ergo holdings stored using a secure hardware wallet, or an appropriate mobile wallet and only use the node wallet for performing transactions.

As always, if you run into trouble with any part of this guide, please contact me here via the newsletter or on Twitter/X (@brav0charlie) and I’ll be happy to lend a hand.

Happy building!