Quickstart

Get started with Obol Stack in under 5 minutes

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.

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).

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

Installation options

Default installation

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/

Specific version

Development mode

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

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

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

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

• Installing networks - Learn how to deploy different blockchain networks.

• Installing apps - Deploy additional applications on your stack.

• FAQ - Common questions and troubleshooting.