NOTE! The steps below are no longer valid. See this official video from the project to see the updated setup procedure. I'm aiming to update the article to correspond with the video when I have time.
In this tutorial we take a step by step approach to setting up a VSC node. Almost no prerequisites are required, and in theory you should be able to follow along regardless of your technical skill level. This is intended to compliment the official doc pages and the video Install VSC node via ansible, to provide additional details in the setup of a VSC node and hopefully make running a node more accessible to even more people.
This post was posted on: Feb 25, 2024
Last updated: April 3, 2024
I have yet to update the full post. See the cheat sheet section at the bottom for useful commands and info (for the updated setup guide).
Since you're reading this, I assume you already know what 
*hardware requirements may increase in the future. Check official doc pages (link at the top) for up-to-date details.
I won't be covering a general installation of an Ubuntu server here, as there are plenty of good tutorials available for that (and it's not very difficult). Here's a brief outline of the process though;
Now you can click Save > Next and write everything to your memory card. This process will take a few minutes. When the process is done, remove the memory card from your computer and insert it into your Raspberry Pi.
Now all you need to do is to plug in the power cord and it will boot up.
The easiest way to do this is probably to log into the router of your local network and check what the IP address of your server is. You should be able to find this somewhere under Connected devices - look for the hostname you selected when you set up your server.
Note: This is a general pointer, as all router interfaces are different - look it if you need further assistance, there are plenty of resources for any router out there).
In my case, I found that my server IP was 192.168.1.108
You'll be interacting with your server through a terminal window on your main computer/workstation. To bring up a terminal window;
cmd, then Enter.In the terminal type in the username and the the local IP Address of your server. In my case I chose the username mp and the IP Address is 192.168.1.108, so the command I have to use is
ssh mp@192.168.1.108
Hit Enter and you should be prompted to type inn your password (even if it seems like nothing is happening when you type, it's being registered). Then press Enter again and your terminal window should look something like this:
If you've made it this far, give yourself a pat on the back! The hard part is done, and now we've got everything ready for setting up our node.
Before we can do any serious work, we need to run a full system update. To do this, copy the following command, right click in your terminal window to paste it. Then Enter to run the command.
sudo apt update && sudo apt upgrade && sudo apt dist-upgrade
You'll be prompted for your password again. Then you may be prompted several times to input either Y or N. Type Y and Enter every time. This process will take some minutes.
When all the upgrades are done and you return to the command prompt, it's a good idea to reboot your server when all the upgrades are complete. Do this with the command
sudo shutdown -r now
'lm-sensors' will allow us to monitor the system's temperature. 'git' is necessary to sync the VSC repository. 'sshpass' is required to set up the node. To install all three, run this command:
sudo apt install lm-sensors git sshpass
Run these three commands in order.
sudo apt install docker docker-compose
sudo usermod -aG docker $USER
sudo service docker start
Run command;
sudo apt install python3-pip
Run command;
python3 -m pip install --user ansible
If you require further details or run into issues, here's Ansible's official documentation.
To fetch all necessary files from the VSC repository, run this command.
git clone https://github.com/vsc-eco/vsc-node
This creates a new folder in your home folder. To enter that folder, run
cd vsc-node
Your prompt will change, indicating that you're now in the vsc-node-folder. To view its contents, run ls, like so:
First run this command;
echo -e "[defaults]\nhost_key_checking = false" > ansible.cfg
Then copy the following lines of text;
vsc_nodes:
hosts:
raspberrypi:
ansible_host: 192.168.0.100 #changeme
ansible_user: pi #changeme
ansible_password: <mypassword> #changeme
ansible_become_pass: <mypassword> #changeme
Then run the command
nano inventory.yml
This creates and opens a new, empty yml-file in your vsc-node folder. Right click in your terminal window to paste the text copied from the previous step.
Edit each line and replace what's already there with your own data. The password in both password fields should be the same. It should look something like this when you're done.
When you're done editing:
Copy and execute the following command:
ansible-playbook deploy/ansible/docker_install/playbook.yml -i inventory.yml
You will now be prompted for your nodes' Hive Account Name, Posting key and Active key (the Private keys, not the Public ones). Enter one at a time,
Check the video from timestamp 02:01 if you want to see how this process should unfold. It can take several minutes. If you end up back at your regular prompt without errors and see something like this, congrats! You're node should now be up and running.
Run the command docker ps to see which docker processes are running. There should be 3; vsc-node, ipfs/kubo and mongo.
To view your node logs live, enter this command:
docker logs vsc-node --follow --tail=10
As long as it's updating regularly and looks something like this, it means everything is working as intended.
When you're done watching the log file, hit Ctrl + C to return to the command prompt.
You can now start looking for your node in the VSC Witnesses List.
Note that it may take some time before it says "Enabled" and "Up to Date" . Notice those highlighted fields in the screenshot of the log above, "blockLag" and "parseLag". These numbers will decrease with time, until they reach zero. And your node may not appear before that. This can take several hours.
Automatic should happen automatically, but in my case they have not on a couple of occasions already, leaving my node with this status (enabled: True - Up to date: False)
It's crucial that your node is up to date, so in cases like this you'll need to update it manually. To run the update, make sure you're in the vsc-node-folder;
cd vsc-node
and then run the the update.sh-script with;
./update.sh
If you get this error you need to manually create your .env file and insert your keys into that file. To do that do the following:
cp .env.example .env
then open the file with
nano .env
Fill in the node account name, posting key and active key, then save the file with Ctrl + o, then Ctrl + x. Now try to run the update script again.
This most likely means you've made local changes in your vsc-folder. To fix, run this command, then try the update script again.
git reset --hard
Here are some general commands that are good to have at hand while maintaining your server. The VSC software itself should update automatically, so you shouldn't need to worry about that.
If you use the Up (and Down) Arrow keys, you can scroll through your command history. This way you usually don't need to type out every command every time.
sudo apt update && sudo apt upgrade && sudo apt dist-upgrade
sudo shutdown -r now
sensors
docker ps
docker logs vsc-node --follow --tail=10
Sometimes your node don't update by itself, so it's necessary to do it manually. To do this we first need to remove all docker containers. This is done with the following command.
docker rm $(docker ps -aq) -f
Then, in vsc-node-folder, run
sudo ./update.sh
If you found this useful, feel free to leave a comment, upvote or reblog.
Thank you for reading!
To learn more about Hive, this article is a good place to start: What is Hive?. If you don't already own a Hive account, go here to get one.
