Klever Node Manager

What it does

Running a validator means running Docker containers, keeping configuration files up to date and looking after BLS keys. The Node Manager wraps all of this in one interactive script with beginner-friendly prompts and safety checks.

Requirements

• Operating system: Ubuntu 20.04 or newer, Debian 10 or newer. Other distributions are refused.
• Access: root or sudo.
• Docker and jq: installed automatically if they are missing (Docker from the official Docker repository).
• Internet access to Docker Hub (image and tag list) and to the official Klever configuration backup backup.mainnet.klever.org. If that is unavailable, the script falls back to the configuration files in the klever-io/klever-go repository on GitHub.

Installation

1. Download the script Run this on your server, or upload the file with SCP/SFTP.

   wget https://klever-radar.de/software/nodes/klever_node_manager.sh

2. Make it executable

   chmod +x klever_node_manager.sh

3. Run it

   sudo ./klever_node_manager.sh

The script also understands --help and --version.

The main menu

************************************************
*        Klever Node Management Suite          *
*           Created by CryptoJaeger^^          *
************************************************

Please select an option:

  [1] Create New Nodes
  [2] Update Existing Nodes
  [3] Manage Nodes (Start/Stop/Status)
  [4] Exit

Enter your choice [1-4]: _

What the script sets up

Every node gets its own folder and its own Docker container. With the default installation directory the first node looks like this:

1 · Create new nodes

Choose [1] in the main menu. The script asks for the following, in this order:

1. Existing nodesThe script checks for nodes that are already there. If it finds some, it lists them with port and status and asks whether you want to continue.
2. Installation directoryPress Enter for the default /opt.
3. DockerInstalled automatically if missing.
4. Image tagThe script shows the 15 most recent tags of kleverapp/klever-go (development, testnet, devnet, alpine and validator-only tags are left out). Press Enter for latest, type a number, or type a tag yourself. The image is then pulled.
5. Number of nodesHow many nodes should be created in this run.
6. Normal or fallbackSee the table below.
7. New BLS keys?Only asked for normal nodes. Fallback nodes never generate keys.
8. SummaryPath, number, type, key generation, node names and ports. Confirm with y and the nodes are created.

Normal nodes and fallback nodes

Example: first installation with three normal nodes

Select option: 1

Checking for existing Klever nodes...
No existing nodes found. You can create new nodes.

Enter installation directory (default: /opt): /opt
Installation directory: /opt

Available image tags:
  [ 1] latest                         (default)
  [ 2] v1.7.14
  ...
Select tag number or type custom tag [latest]:
Selected: kleverapp/klever-go:latest

How many nodes do you want to create? 3
Are these fallback nodes? (y/n): n
Do you need to generate new BLS validator keys? (y/n): y

Summary:
  • Installation path: /opt
  • Number of nodes: 3
  • Node type: Normal (active validator)
  • Generate new keys: Yes
  • Node names: node1 - node3
  • REST API ports: 8080 - 8082

Proceed with node creation? (y/n): y

Creating node1...
  ✓ Directories created
  ✓ Configuration downloaded from primary source
  ✓ Validator keys generated
  ✓ Container started successfully
✓ Node node1 created successfully!
[... node2 and node3 the same ...]

✓ Successfully created: 3

⚠ IMPORTANT:
New 'validatorKey.pem' files have been generated in each node's config directory.
Please ensure these keys are backed up securely!

Shortened example. The version numbers in the tag list depend on what is currently published.

Adding more nodes later

If nodes already exist, the script lists them, takes the highest node number and port, and continues after that. With node1 to node3 on ports 8080 to 8082, two new nodes become node4 and node5 on ports 8083 and 8084.

Existing nodes detected:

  • node1 - Port: 8080 - Status: Running
  • node2 - Port: 8081 - Status: Running
  • node3 - Port: 8082 - Status: Running

Used ports: 8080 8081 8082
New nodes will automatically use the next available ports starting from 8083.

Do you want to continue creating additional nodes? (y/n): y

After the creation

• New keys generated: back up every validatorKey.pem in /opt/nodeX/config/.
• Fallback nodes: copy the validatorKey.pem of your main node into the config folder of each fallback node, then restart it with docker restart klever-nodeX.
• Own keys for normal nodes: place your validatorKey.pem in /opt/nodeX/config/ and restart the container.

2 · Update existing nodes

Choose [2] to bring all your nodes to a new Docker image and the latest configuration. The script updates all nodes it finds, one after the other.

1. OverviewEvery node is listed with path, container, REST API port, type (normal or fallback) and display name. If all nodes are fallback nodes, the script warns you.
2. Image tagThe same tag selection as when creating nodes. The image is pulled.
3. Version checkThe summary shows the running and the target version and tells you whether a new image is available.
4. ConfirmFor each node the script downloads the latest configuration, stops and removes the old container, repairs permissions and starts a new container with the same settings.

Update Summary:
  • Total nodes to update: 3
  • Normal validators:     2
  • Fallback nodes:        1
  • Configuration source:  backup.mainnet.klever.org (fallback: klever-io/klever-go)
  • Docker image:          kleverapp/klever-go:latest

  • Running version:       v1.7.13
  • Target version:        v1.7.14
    ↑ New image available!

Proceed with the update? (y/n): y

Example. The version numbers are illustrative.

3 · Manage nodes

Choose [3] for the daily work. The screen shows a status table that refreshes whenever you return to the menu:

  Node          Status     Port   Version                  Uptime     Nonce        Sync
  ─────────────────────────────────────────────────────────────────────────────
  node1         Running    8080   v1.7.14                  5d 12h     33951786     Synced
  node2         Running    8081   v1.7.14                  5d 12h     33951786     Synced
  node3         Stopped    8082   v1.7.14                  --         --           --
  node4         Running    8083   v1.7.14                  2h 34m     33951785     Syncing

Options:
  [1] Start Nodes          [5] Refresh Status
  [2] Stop Nodes           [6] Fix Node Permissions
  [3] Restart Nodes        [7] Extract BLS Public Keys
  [4] View Node Logs       [b] Back to Main Menu

Illustrative values. Nonce and sync state come from the REST API of each running node.

BLS keys

Every validator node needs a validatorKey.pem in its config folder. The script reads the BLS public key from this file. You need it when you register your validator on the Klever blockchain.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Node: node1
Path: /opt/node1/config/validatorKey.pem

BLS Public Key:
a1b2c3d4e5f6...   (your key is shown here)

Keys found: 1

• Normal validators: let the script generate the key when you create the node, or place your own validatorKey.pem in /opt/nodeX/config/ and run docker restart klever-nodeX.
• Fallback nodes: use the same validatorKey.pem as your main validator, copy it into the fallback node's config folder and restart the container.
• A missing or unreadable key file is reported as not found or could not extract.

Good to know

Permissions

All node folders must belong to user 999:999. The script sets this during creation and updates, and option 3 → [6] repairs it.

/opt/nodeX/config/   -> 999:999
/opt/nodeX/db/       -> 999:999
/opt/nodeX/logs/     -> 999:999
/opt/nodeX/wallet/   -> 999:999

Ports

The first node gets port 8080, every further node the next free port. The script checks that the port is not in use; if it is, that node is skipped.

Directory protection

The script never overwrites an existing node. If /opt/node1/ or the container klever-node1 already exists, that node number is skipped. Use a different number, or back up and remove the old folder first. If creating a node fails halfway, the half-finished folder is removed again.

Troubleshooting

"This script must be run as root or with sudo"

sudo ./klever_node_manager.sh

A node will not start

1. Look at the log:

   docker logs klever-node1

2. Repair the permissions: option 3 → [6] Fix Node Permissions.
3. Check that the key file is there:

   ls -la /opt/node1/config/

The port is already in use

The script notices this and skips the node. To find out what is using the port:

sudo ss -tuln | grep :8080

Then stop the other service or create the node with a different number.

The tag list could not be loaded

If Docker Hub cannot be reached, the script says so and asks for the tag directly. Press Enter for latest or type a tag.

Useful Docker commands

# Running containers
docker ps

# All containers, including stopped ones
docker ps -a

# Stop, start or restart a node
docker stop klever-node1
docker start klever-node1
docker restart klever-node1

# Live log, last 100 lines
docker logs -f --tail 100 klever-node1

# Node folder and config files
ls -la /opt/node1/
ls -la /opt/node1/config/

Function overview