Cassandra Setup Guide

Questions / Help
,
1

Recommended System
The minimum specification recommended to operate a Cassie validator instance is as follows.

  • 4 core CPU
  • 12GB RAM (more is better)
  • SATA SSD
  • 100Mbit downstream / 30Mbit upstream connection

Those with higher specification machines are able to run multiple instances of validators.

Java Setup
First you need to install Java if you don’t already have it.
https://www.oracle.com/uk/java/technologies/downloads/#java21

If you’re a more technical user and know what you are doing, preferable to get the JDK as there is additional tooling we can use to identify any issues.

Cassie is compatible with Java21+
(You can check your Java version with: ‘java -version’ on the console)

Default install settings should be fine for most users, again, if you’re technical you can install it with whatever options you like.

Configuration
Cassie comes with a default config file embedded in the Jar. This is needed to identify the bootstrap nodes (so you can actually connect), defines the Universe instance, whether sharding is enabled and a bunch of other stuff.

It is fine to use the default configuration included, but if you are a more technical user, there are a few things you can do to help things run a bit smoother.

I’ll provide a default.config file alongside each jar for easy editing. It is the same as the one included in the jar.

If you have a directly connected static IP address (not behind a router, for example 192.168.##.## address) , it is beneficial for you to define it in the config

network.address=IPV4 or IPV6

It is also beneficial to open or forward the Universe port (30000) to your machine you are using as a validator if you have the bandwidth and set the following in the config

node.service.gateway=true

This is the port which listens for incoming connections and initiates a key swap. If you are behind a router, then forward to the LAN address of your validator on your internal network.

You should also allow outbound and inbound connections to the Universe port in your firewall if you have one enabled.

If you need to change the Universe port you can do so by using the following flag in the config

network.port=PORT

There are also ports for the REST API (8080) and WebSockets (8880) defined in the config. Open firewalls and forward these accordingly too if you can, these are useful for dApps with hosted frontends and clients to submit transactions.

You can also change these from the defaults if you like, or if they clash with some existing service. The ports are communicated to peers/clients so they can interact if they are different to the defaults.

api.port=PORT
websocket.port=PORT

As we progress with testing there are some other config options that will be useful to us, so this section will likely grow over time.

Running
It is strongly recommended to run Cassie from the command line.

Make sure the Cassie jar file is on the drive with the minimum amount of space you want then enter the following command

java -Xms10G -Xmx10G -jar cassandra.jar -console

(you can modify the -Xms and -Xmx parameters if you have more than 12GB RAM)

The REST API port is 8080 by default, if there are problems with the execution, either start via superuser (sudo java -jar cassandra.jar -console) or reconfigure the API port

That should be all you need to do and Cassie should start up with a bunch of information messages printed in the command line window as it does. Once startup is complete you will be presented with a console cursor > where you can enter commands and query your Cassie instance.

If you have ran previous versions of Cassie you will want to delete the “database” directory it previously created. It might be useful to produce a small script that you can execute to delete the database and then run Cassie for convenience if you know how to do that.

If you also created a custom default.config file, you will want to copy the “universe” field from the provided config file otherwise Cassie will complain on startup, or not be able to connect to the network.

The more advanced among you might want to tweak the java environment with additional memory settings etc but providing your machine meets the minimum requirements you shouldn’t have to specify any.

This is what you’ll see when running the initial startup command

java -Xms10G -Xmx10G -jar cassandra.jar -console or
sudo java -Xms10G -Xmx10G -jar cassandra.jar -console

image
image1455×432 18.4 KB

When you see “boostrapper terminating” the node has started and you can enter in one of the commands below to check the state of the node and network

Console
After startup the default configuration presents a console to accept Cassie commands.

Some common ones are as follows:

ledger
information about your Cassie instance such as if it is in sync, how many proposals it has processed, transactions, current throughput statistics etc

network
lists the network peers your instance is currently connected to. Both within its local shard and remote shards (if relevant)

network -known
lists all the validators on the network. Note: for the purpose of testing a network peer might be running 2 or more validators, so “network -known” will always return more than just “network”

network -stats
produces statistical information about network usage such as current bandwidth, gossip statistics, etc

As we progress through testing I will detail more useful functions of the console as we need them.

Output of the ‘ledger’ console command

cassie
cassie939×335 119 KB

Console messages
This is a message that originates from the internet and can be safely ignored

[qtp937908854-57] INFO spark.http.matching.MatcherFilter - The requested route [www.google-analytics.com:443] has not been mapped in Spark for Accept: [null]

Appendix 1. - Standalone Ubuntu Linux installation
Simple Ubuntu Linux setup instructions

  1. Download Ubuntu 22.04.04 Server ISO from HERE

  2. Burn ISO as a boot disc to USB using software like Balena Etcher HERE

  3. Insert boot USB and start up machine. It will ask if you want to install Ubuntu, follow the instructions to install.

  4. Once Ubuntu is installed at a munimum you should make sure the latest updates are applied by running

sudo apt update && sudo apt upgrade
sudo apt dist-upgrade && sudo apt autoremove
sudo reboot
  1. Log bak in and install the Java SDK (version 21)

> sudo apt install openjdk-21-jdk openjdk-21-jre

Appendix 2. - Starting multiple Cassandra instances on one machine
If you want to start several instances on one machine, you must copy them into separate directories and store a customized default.config there.
The following posts must be adjusted for each instance:

api.port=PORT (default: 8080)
websocket.port=PORT (default: 8880)
network.port=PORT (default: 30000)

At least the network.port must be enabled in the firewall.

In the current tests, 4 cores and 8 GB of RAM were sufficient for each instance. Each instance places a load on the disk IO, please pay attention to this and to the additional network bandwidth required.

Tipps

2 Likes