Skip to main content
Version: v1.8

Quickstart

This guide walks you through installing the Obol Stack and running your first blockchain network locally.

Prerequisites​

  • Docker installed and running on your machine.
  • macOS or Linux operating system.
  • At least 8 GB of RAM available.
  • Terminal access.
info

Ensure Docker is running before proceeding. You can verify this by running docker info in your terminal.

Step 1: Install Obol Stack​

Run the bootstrap installer to set up your environment:

bash <(curl -s https://stack.obol.org)

The installer will:

  1. Validate prerequisites (Docker daemon).
  2. Create the directory structure.
  3. Install the obol CLI binary.
  4. Install pinned versions of dependencies (kubectl, helm, k3d, helmfile, k9s).
  5. Configure your PATH.
  6. Add obol.stack to /etc/hosts (requires sudo).
tip

The installer supports both interactive and non-interactive modes. For scripted installations, use environment variables like OBOL_MODIFY_PATH=yes.

Installation options​

Standard installation using XDG Base Directory specification:

bash <(curl -s https://stack.obol.org)

Files are installed to:

  • Config: ~/.config/obol/
  • Data: ~/.local/share/obol/
  • Binaries: ~/.local/bin/

Step 2: Initialize and start the cluster​

Initialize the stack configuration:

obol stack init

This generates a unique cluster ID and prepares the k3d configuration.

Start the Kubernetes cluster:

obol stack up
info

The first startup may take a few minutes as Docker pulls the required images for k3d and the default applications.

Step 3: Verify the installation​

Check that the cluster is running:

obol kubectl get nodes

You should see output similar to:

NAME                            STATUS   ROLES                  AGE   VERSION
k3d-obol-stack-xxxxx-server-0   Ready    control-plane,master   1m    v1.31.4+k3s1
k3d-obol-stack-xxxxx-agent-0    Ready    <none>                 1m    v1.31.4+k3s1
k3d-obol-stack-xxxxx-agent-1    Ready    <none>                 1m    v1.31.4+k3s1
k3d-obol-stack-xxxxx-agent-2    Ready    <none>                 1m    v1.31.4+k3s1

List available networks:

obol network list

Step 4: Install a network​

Install an Ethereum node on the Hoodi testnet:

obol network install ethereum --network=hoodi

This creates a network configuration with an auto-generated deployment ID (e.g., knowing-wahoo).

Deploy the network to the cluster:

obol network sync ethereum/knowing-wahoo
warning

Replace knowing-wahoo with the actual deployment ID shown in your terminal output.

Check the deployment status:

obol kubectl get pods -n ethereum-knowing-wahoo

Step 5: Explore your cluster​

Use k9s for a visual interface to explore your cluster:

obol k9s

Or check specific resources:

# View all pods across namespaces
obol kubectl get pods -A

# View logs for a specific pod
obol kubectl logs -n ethereum-knowing-wahoo <pod-name>

# View persistent volume claims
obol kubectl get pvc -A

Stopping and cleaning up​

Stop the cluster​

To stop the cluster while preserving all data:

obol stack down

Restart the cluster​

To restart a previously initialized cluster:

obol stack up

Remove everything​

To completely remove the cluster and configuration:

obol stack purge
warning

The purge command removes the cluster configuration. To also remove persistent data (blockchain data, PVCs), add the -f flag:

obol stack purge -f

This action is irreversible.

Next steps​