The Obol Stack: Decentralised Applications For Ethereum

Overview

The Obol Stack is a framework to make it easier to distribute decentralised applications (dApps), and easier to install and run them locally. The stack is built on Kubernetes, with Helm as a package management system.

Getting Started

Important

The Obol Stack is alpha software. It is not complete, and it may not be working smoothly. If you encounter an issue that does not appear to be documented, please open a GitHub issue if an appropriate one is not already present.

Prerequisites

The Obol Stack requires Docker to run a local Kubernetes cluster. Install Docker:

• Linux: Follow the Docker Engine installation guide
• macOS/Windows: Install Docker Desktop

Installation

The easiest way to install the Obol Stack is using the obolup bootstrap installer.

Run the installer with:

curl -fsSL https://raw.githubusercontent.com/ObolNetwork/obol-stack/main/obolup.sh | bash

What the installer does:

1. Verifies Docker is running
2. Installs the obol CLI binary to ~/.local/bin/obol
3. Installs required dependencies (kubectl, helm, k3d, helmfile, k9s) to ~/.local/bin/
4. Adds obol.stack to your /etc/hosts file (requires sudo) to enable local domain access
5. Prompts you to add ~/.local/bin to your PATH by updating your shell profile
6. Prompts you to start the cluster and open the Obol application in your browser

PATH Configuration:

The installer will detect your shell (bash/zsh) and ask if you want to automatically add ~/.local/bin to your PATH. If you choose automatic configuration, it will add this line to your shell profile (~/.bashrc or ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

After installation, reload your shell configuration:

# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

Manual PATH Configuration:

If you prefer to configure PATH manually, add this line to your shell profile:

# Add to ~/.bashrc (bash) or ~/.zshrc (zsh)
export PATH="$HOME/.local/bin:$PATH"

Then reload your shell or start a new terminal session.

Using obol without PATH:

If you haven't added ~/.local/bin to your PATH, you can always run commands directly:

~/.local/bin/obol version
~/.local/bin/obol stack init

Verify the installation:

obol version

Quick Start

Once installed, you can start your local Ethereum stack with three commands:

# Initialize the stack configuration
obol stack init

# Start the Kubernetes cluster
obol stack up

# View cluster (opens interactive terminal UI)
obol k9s

The stack will create a local Kubernetes cluster and the Obol Stack frontend will be available at:

• Obol Stack: http://obol.stack (or http://localhost if using port 80)

Managing the Stack

Start the stack:

obol stack up

Stop the stack:

obol stack down

View cluster (interactive UI):

obol k9s

View cluster logs:

obol kubectl logs -n <namespace> <pod-name>

Remove everything (including data):

obol stack purge -f

Warning

The purge command permanently deletes all cluster data and configuration. The -f flag is required to remove persistent volume claims (PVCs) owned by root. Use with caution.

Working with Kubernetes

The obol CLI includes convenient wrappers for common Kubernetes tools. These automatically use the correct cluster configuration:

# Kubectl (Kubernetes CLI)
obol kubectl get pods --all-namespaces

# Helm (Kubernetes package manager)
obol helm list --all-namespaces

# K9s (interactive cluster manager)
obol k9s

# Helmfile (declarative Helm releases)
obol helmfile list

Troubleshooting

Port 80 Already in Use

The Obol Stack is configured to run on ports 80 and 443 by default. If you have another service using these ports, the cluster may fail to start.

To fix this:

1. Edit the k3d configuration file:

   $EDITOR ~/.config/obol/k3d.yaml

2. Find the ports section that looks like this:

   ports:
     - port: 80:80
       nodeFilters:
         - loadbalancer
     - port: 8080:80
       nodeFilters:
         - loadbalancer
     - port: 443:443
       nodeFilters:
         - loadbalancer
     - port: 8443:443
       nodeFilters:
         - loadbalancer

3. Remove the 80:80 and 443:443 entries (keep the 8080 and 8443 entries):

   ports:
     - port: 8080:80
       nodeFilters:
         - loadbalancer
     - port: 8443:443
       nodeFilters:
         - loadbalancer

4. Restart the cluster:

   obol stack down
   obol stack up

After this change, access the Obol Stack frontend using port 8080:

• Obol Stack: http://obol.stack:8080 (or http://localhost:8080)

Tip

If ports 8080 or 8443 are also in use, you can change them to any available port. For example, change 8080:80 to 9090:80 and 8443:443 to 9443:443. Then access the application at http://obol.stack:9090 or http://localhost:9090

Where Files Are Stored

The Obol Stack follows the XDG Base Directory specification:

• Configuration: ~/.config/obol/ - Cluster config, kubeconfig, application manifests
• Data: ~/.local/share/obol/ - Persistent volumes and database storage
• Binaries: ~/.local/bin/ - The obol CLI and dependencies
• Logs: ~/.local/state/obol/ - Structured logs for debugging

Uninstalling Obol Stack

To completely remove the Obol Stack from your system:

1. Stop and remove the cluster:

~/.local/bin/obol stack purge -f

Note

The -f flag is required to remove persistent volume claims (PVCs) that are owned by root. Without this flag, data volumes will remain on your system.

2. Remove Obol binaries:

rm -f ~/.local/bin/obol \
      ~/.local/bin/kubectl \
      ~/.local/bin/helm \
      ~/.local/bin/k3d \
      ~/.local/bin/helmfile \
      ~/.local/bin/k9s \
      ~/.local/bin/obolup.sh

3. Remove Obol directories:

rm -rf ~/.config/obol \
       ~/.local/share/obol \
       ~/.local/state/obol

Note

This process removes Obol binaries from ~/.local/bin/. If you installed kubectl, helm, k3d, helmfile, or k9s separately before installing Obol, make sure not to delete those binaries. The PATH configuration in your shell profile is left unchanged.

Updating the Stack

To update to the latest version, simply run the installer again:

curl -fsSL https://raw.githubusercontent.com/ObolNetwork/obol-stack/main/obolup.sh | bash

The installer will detect your existing installation and upgrade it safely.

Development Mode

If you're contributing to the Obol Stack or want to run it from source, you can use development mode.

Setting up development mode:

1. Clone the repository:

   git clone https://github.com/ObolNetwork/obol-stack.git
   cd obol-stack

2. Run the installer in development mode:

   OBOL_DEVELOPMENT=true ./obolup.sh

What development mode does:

• Uses a local .workspace/ directory instead of XDG directories (~/.config/obol, etc.)
• Installs a wrapper script that runs the obol CLI using go run (no compilation needed)
• Code changes are immediately reflected when you run obol commands
• All cluster data, configuration, and logs are stored in .workspace/

Development workspace structure:

.workspace/
├── bin/                         # obol wrapper script and dependencies
├── config/                      # Cluster configuration
│   ├── k3d.yaml
│   ├── .cluster-id
│   ├── kubeconfig.yaml
│   └── applications/
├── data/                        # Persistent volumes
└── state/                       # Logs
    └── {cluster-id}/
        └── 2025-01-15.log

Making code changes:

Simply edit the Go source files and run obol commands as normal. The wrapper script automatically compiles and runs your changes:

# Edit source files
$EDITOR cmd/obol/main.go

# Run immediately - no build step needed
obol stack up

Switching back to production mode:

First, purge the development cluster to remove root-owned PVCs, then remove the .workspace/ directory and reinstall:

obol stack purge -f
rm -rf .workspace
./obolup.sh

Note

The obol stack purge -f command is necessary to remove persistent volume claims (PVCs) owned by root. Without the -f flag, these files will remain and may cause issues.

Project Status

This project is currently in alpha, and should not be used in production.

The stack aims to support all popular Kubernetes backends and all Ethereum client types, with a developer experience designed to be useful for local app development, through to production deployment and management.

Contributing

Please see CONTRIBUTING.md for details.

License

This project is licensed under the Apache License 2.0.