🧭 Geth Private Network Setup (Local & Playground OSS)

If you want to try this from scratch read this section about clearing up

Clearing everythign down and starting from scratch Overview

This document provides step-by-step instructions for installing and running a Geth private Ethereum network, both locally (using Kind and Kurtosis) and on mqube-playground.com (the test OSS cluster).

---

🚀 Overview

The private Ethereum network runs using the ethpandaops/ethereum-helm-charts Helm chart.
Installation is performed via:

helm upgrade --install ...

Helm values are overridden through custom values.yaml files to allow easy deployment in environments such as staging, or production using Jenkins X (JX) and helmfiles.yaml.

You’ll need two main components:

1. Helm values (values.yaml) — defines configuration for Helm installations (used in JX via helmfiles.yaml).
2. Network setup files — includes genesis.json, config.yaml, genesis.ssz, and related files defining the private chain configuration.

---

⚙️ Network Configuration Files

The default chart is configured for a global Ethereum testnet, but we’re running a private network instead.

Custom configuration files are stored in this repository under:

/network-configs

These override the defaults from the Helm chart.

---

🧰 Generating the Private Network Configuration with Kurtosis

We use Kurtosis — a development orchestration tool similar to Docker Compose or Helm, but designed for more complex stack setups (especially for blockchain testnets).

Kurtosis simplifies generating the configuration files needed for a local Ethereum network.

🧑‍💻 Install Kurtosis

brew install kurtosis-tech/tap/kurtosis-cli

🧱 Set up a Kind Cluster

Kurtosis runs best with Kind (Kubernetes-in-Docker) on macOS:

brew install kind
kind create cluster --name kurtosis

Then connect Kurtosis to that cluster:

kurtosis cluster set kind-kurtosis
kurtosis cluster ls
kurtosis engine status

Start or restart the Kurtosis engine:

kurtosis engine start
# or
kurtosis engine restart

You can monitor logs using:

kurtosis gateway

🧹 Clean Up Old Enclaves

If you previously set up a testnet, clean it up first:

kurtosis enclave rm -f my-testnet
kurtosis clean -a

🌐 Launch a Private Ethereum Network

Run the official ethpandaops Ethereum package inside a new enclave:

kurtosis run --enclave my-testnet github.com/ethpandaops/ethereum-package

📁 Download Generated Config Files

After setup, download the configuration files used/generated by Kurtosis:

kurtosis files download my-testnet el_cl_genesis_data ./out/el_cl_genesis_data

These are the files uploaded to this repo under /network-configs, replacing the testnet files from the Helm chart.

📁 Download Generated Keys files

Kurtosis doesn't produce the key files as part of the config download we do above , it doesn't actually produce them as enclave files so you can't use

kurtosis files download

You need to downloand them from the image on the cluster , there is a K8 job that runs and checks for keys and updates the validator , this often completes so you can get them from that job but only if running (which is unlikley) So the script tries to get them from there , but otherwise it gets them from the other services that the validaor job uses to build them , so either way you end up with the 64 validator keys that are then created in the secret (below) which the validaotr uses in it's init script to import and use for validation (or helm installed validator)

There are some scripts to help do this

./scripts/getKurtosisKeys.sh 

Then we need to create the secret itself with the JSON key files and the Password file

./scripts/createSecretFromKeys.sh

This secret is referenced from the validator init containers to import all the accounts to use for validation these accounts are the accounts used in genesis.ssz which was generated as part of the config files above

You can see the init containers logic for importing these secrets here

helm-configs/validator.yaml See the validator config for details.

Kurtosis Docker

If you decide it was too much to use kind and install kurtosis (I would though as it's much easier using kind and Kurtosis) you can use the docker containers they (kurtosis) use and run them directly

Docker Kurtosis Overview

---

🏗️ Deploying the Private Network (Execution, Beacon, Validator)

Read the clearing up section , but if you want to use the config files in this repo then you can and miss the steps above , but read the clear up section to understand this and if not and your producing the config files remember to push back to main on this report or change you helm-config yaml files to use a local directoy instead of this repo

Geth (Execution Node)

To install the Geth execution node locally or on the Playground OSS cluster:

helm upgrade --install geth-devnet ethpandaops/geth \
  -f https://raw.githubusercontent.com/spring-financial-group/ethereum-config-chains/main/helm-configs/geth-execution.yaml \
  --namespace devnet --create-namespace

💡 Use the Helm chart directly from ethpandaops/ethereum-helm-charts, or reference it from this repo.
On JX (e.g., staging), prefer using helm repo add in your Helmfile setup.

Beacon Node

 helm upgrade --install beacon-devnet ethpandaops/prysm \
  -f https://raw.githubusercontent.com/spring-financial-group/ethereum-config-chains/main/helm-configs/beacon-chain.yaml \
  --namespace devnet --create-namespace

Validator Node

helm upgrade --install validator-devnet ethpandaops/prysm \
  -f https://raw.githubusercontent.com/spring-financial-group/ethereum-config-chains/main/helm-configs/validator.yaml --namespace devnet --create-namespace

These three components—Geth, Beacon, and Validator—together form a complete Proof-of-Stake (PoS) Ethereum private network.

For more details on Prysm (Beacon & Validator):

📘 Prysm Documentation
💻 Geth (go-ethereum) Repository

---

🔍 Blockscout Setup

Blockscout provides an explorer interface for viewing your private network.

We deploy it on the playground OSS cluster.

1. Install PostgreSQL

Install a secret first that psotgress will use

kubectl apply -f https://raw.githubusercontent.com/spring-financial-group/ethereum-config-chains/main/helm-configs/blockscout-db-auth.secret.yaml  --namespace devnet

helm upgrade --install blockscout-db oci://registry-1.docker.io/bitnamicharts/postgresql   -n devnet -f https://raw.githubusercontent.com/spring-financial-group/ethereum-config-chains/main/helm-configs/block-postgresql.yaml

⚠️ When uninstalling, remember to delete the PVC to ensure a clean database reset:

kubectl delete pvc data-blockscout-db-postgresql-0 -n devnet

This ensures that your next deployment starts with a fresh, empty database.

---

2. Create the Stats Database

Blockscout’s Stats service (written in Rust) requires a manual DB creation step because it doesn’t support sslmode=disable.

Run the helper script in this repo:

export NS=devnet
./scripts/createStatsDB.sh

---

3. Create the PostgreSQL Secret

This secret stores database credentials for the Blockscout Helm chart:

./scripts/postgress-secret-script.sh

---

4. Install Blockscout

 helm upgrade --install blockscout blockscout/blockscout-stack   -n devnet -f https://raw.githubusercontent.com/spring-financial-group/ethereum-config-chains/main/helm-configs/blockscout-stack.yaml

🛈 You may see warnings about environment variables being overridden — this is expected due to how the chart merges environment configs.

---

🌍 Access the Explorer

Once deployed, you can view your private network in Blockscout:

👉 https://mqube-blockscout-frontend.mqube-playground.com/

You will also be exposing the geth-node over rpc-geth-node.mqube-playground.com:

👉 https://rpc-geth-node.mqube-playground.com/

You can test this end point using the below

curl -sS -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' \
  https://rpc-geth-node.mqube-playground.com

---

✅ Summary

Component	Purpose	Helm Config
Geth	Execution Layer	helm-configs/geth-execution.yaml
Beacon	Consensus Layer (Prysm)	helm-configs/beacon.yaml
Validator	Proof-of-Stake Validator	helm-configs/validator.yaml
Blockscout	Blockchain Explorer	helm-configs/block-scout.yaml
PostgreSQL	Blockscout DB	helm-configs/block-postgress.yaml

---

🧩 Notes

• Use Kind for local testing and mqube-playground.com for shared OSS deployments.
• Always clean up PVCs during reinstallation to avoid stale data.
• Kurtosis is optional but extremely useful for generating consistent Ethereum config files.
• Ensure all three core components (Geth, Beacon, Validator) are running before deploying Blockscout.

As an example of the configs now been used in a JX config setup this is for Mqube Staging

https://github.com/spring-financial-group/JX3_Azure_Vault_Dev_Cluster/tree/master/helmfiles/jx-staging/configs

Pre Allocated Accounts

You'll have some pre-funded accounts (these are in genesis.json)

There are some scripts to check these in accounts scripts

Understanding Pre funded Accounts (THESE are NOT the same as the validator accounts you have above) Overview

Setting up the Demo locally using Hardhat

Demo Hardhat Setup