Installation

This guide covers installing Lasso for local development, Docker deployment, and production use.

Prerequisites

Lasso requires:

Elixir 1.17+
Erlang/OTP 26+
Node.js 18+ (for asset compilation)

Check installed versions

elixir --version
# Elixir 1.17.3 (compiled with Erlang/OTP 27)

erl -version
# Erlang (SMP,ASYNC_THREADS) (BEAM) emulator version 14.2.5

node --version
# v18.20.0

Install Elixir and Erlang

If you don’t have Elixir installed:

brew install elixir

wget https://packages.erlang-solutions.com/erlang-solutions_2.0_all.deb
sudo dpkg -i erlang-solutions_2.0_all.deb
sudo apt-get update
sudo apt-get install -y elixir

sudo dnf install -y elixir erlang

See the official Elixir installation guide for more platforms and version managers like asdf.

Install Node.js

For asset compilation:

brew install node

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Local installation (recommended)

Clone the repository

git clone https://github.com/jaxernst/lasso-rpc
cd lasso-rpc

Install Elixir dependencies

mix deps.get

This downloads all required Elixir packages defined in mix.exs.

Start the Phoenix server

mix phx.server

The application will start at http://localhost:4000.You should see output like:

[info] Running LassoWeb.Endpoint with Bandit 1.5.7 at 127.0.0.1:4000 (http)
[info] Access LassoWeb.Endpoint at http://localhost:4000
[watch] build finished, watching for changes...

Verify it's working

Open your browser to:

Dashboard: http://localhost:4000/dashboard
Test RPC endpoint: http://localhost:4000/rpc/ethereum

Or test via curl:

curl -X POST http://localhost:4000/rpc/ethereum \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

The default profile (config/profiles/default.yml) includes free public providers. No API keys required to start.

Docker installation

Using the convenience script

The fastest way to run Lasso with Docker:

git clone https://github.com/jaxernst/lasso-rpc
cd lasso-rpc
./run-docker.sh

This script:

Checks Docker is installed and running
Builds the Docker image
Generates a SECRET_KEY_BASE (if not set)
Starts the container at http://localhost:4000

Manual Docker build and run

For more control:

Build the image

docker build -t lasso-rpc .

The Dockerfile uses a multi-stage build:

Builder stage: Compiles Elixir app, builds assets, creates release
Runtime stage: Minimal image with only release artifacts

Generate a secret key

export SECRET_KEY_BASE=$(openssl rand -base64 48)

Run the container

docker run --rm \
  -p 4000:4000 \
  -e SECRET_KEY_BASE="$SECRET_KEY_BASE" \
  --name lasso-rpc \
  lasso-rpc

The application will be available at http://localhost:4000.

Docker Compose (production)

For production deployments with custom profiles:

docker-compose.yml

version: '3.8'

services:
  lasso:
    image: lasso-rpc:latest
    build: .
    ports:
      - "4000:4000"
    environment:
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
      - PHX_HOST=lasso.example.com
      - PORT=4000
      # Optional: Clustering
      - CLUSTER_DNS_QUERY=lasso.internal
      - LASSO_NODE_ID=us-east-1
    volumes:
      # Mount custom profiles
      - ./config/profiles:/data/config/profiles:ro
    restart: unless-stopped

Run with:

docker-compose up -d

Configuration

Profiles

Profiles define chains, providers, and routing policies. They live in config/profiles/*.yml. The default profile (config/profiles/default.yml) is included and ready to use:

---
name: Lasso Public
slug: default
rps_limit: 100
burst_limit: 500
---

chains:
  ethereum:
    chain_id: 1
    name: "Ethereum Mainnet"
    block_time_ms: 12000

    monitoring:
      probe_interval_ms: 12000
      lag_alert_threshold_blocks: 5

    providers:
      - id: "ethereum_drpc"
        name: "dRPC Ethereum"
        priority: 2
        url: "https://eth.drpc.org"
        ws_url: "wss://eth.drpc.org"
        archival: true

      - id: "ethereum_publicnode"
        name: "PublicNode Ethereum"
        priority: 3
        url: "https://ethereum-rpc.publicnode.com"
        ws_url: "wss://ethereum-rpc.publicnode.com"
        archival: false

      # ... more providers

Environment variables

Profiles support ${ENV_VAR} substitution for API keys:

providers:
  - id: "alchemy"
    url: "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
    ws_url: "wss://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"

Set the variable before starting:

export ALCHEMY_API_KEY=your_key_here
mix phx.server

Unresolved ${ENV_VAR} placeholders will crash at startup. This is intentional to prevent misconfigurations.

Create a custom profile

Create config/profiles/production.yml:

---
name: Production
slug: production
rps_limit: 1000
burst_limit: 5000
---

chains:
  ethereum:
    chain_id: 1
    providers:
      - id: "your_erigon"
        name: "Your Erigon Node"
        url: "http://your-erigon-node:8545"
        ws_url: "ws://your-erigon-node:8546"
        priority: 1
        archival: true

      - id: "alchemy_fallback"
        name: "Alchemy Fallback"
        url: "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
        ws_url: "wss://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
        priority: 2
        archival: true

Access it via:

curl -X POST http://localhost:4000/rpc/profile/production/ethereum \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

See the Configuration guide for complete profile reference.

Multi-node deployment (clustering)

For geo-distributed deployments with aggregated observability:

Enable DNS-based discovery

Set the DNS query for node discovery:

export CLUSTER_DNS_QUERY="lasso.internal"

Your DNS should return all Lasso node IPs.

Set unique node IDs

Each node needs a unique identifier (typically a region name):Node 1 (US East):

export LASSO_NODE_ID=us-east-1
export CLUSTER_DNS_QUERY="lasso.internal"
mix phx.server

Node 2 (EU West):

export LASSO_NODE_ID=eu-west-1
export CLUSTER_DNS_QUERY="lasso.internal"
mix phx.server

Verify cluster formation

Check the dashboard at http://localhost:4000/dashboard. You should see all nodes listed with their regions.Or check via IEx:

iex -S mix phx.server
iex> Node.list()
["lasso@us-east-1", "lasso@eu-west-1"]

Clustering is optional. A single node works great standalone. Clustering aggregates metrics for observability—it doesn’t impact routing decisions.

Each node:

Makes independent routing decisions based on local latency measurements
Shares observability data with the cluster
Allows regional drill-down in the dashboard

See Deployment for production cluster setup.

Troubleshooting

Port already in use

If port 4000 is already in use, set a different port:

PORT=4001 mix phx.server

Or in config/runtime.exs:

config :lasso, LassoWeb.Endpoint,
  http: [ip: {127, 0, 0, 1}, port: String.to_integer(System.get_env("PORT") || "4000")]

Mix not found

If mix is not in your PATH after installing Elixir:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.mix:$PATH"
source ~/.bashrc

Compilation errors

Clear dependencies and rebuild:

mix deps.clean --all
mix deps.get
mix compile

Docker build failures

Ensure you have enough disk space and memory:

docker system prune -a  # Clean up old images
docker build --no-cache -t lasso-rpc .  # Force rebuild

Profile not loading

Check for YAML syntax errors:

# Validate YAML
ruby -r yaml -e "YAML.load_file('config/profiles/default.yml')"

Or check Lasso logs on startup for profile parsing errors.

Next steps

Quickstart

Make your first RPC request through Lasso

Configuration

Customize profiles, providers, and routing strategies

Deployment

Production deployment with clustering

Architecture

Learn how Lasso works under the hood

Get Started

Core Concepts

Configuration

Deployment

Observability

Advanced

Installation

Prerequisites

Check installed versions

Install Elixir and Erlang

Install Node.js

Local installation (recommended)

Docker installation

Using the convenience script

Manual Docker build and run

Docker Compose (production)

Configuration

Profiles

Environment variables

Create a custom profile

Multi-node deployment (clustering)

Troubleshooting

Port already in use

Mix not found

Compilation errors

Docker build failures

Profile not loading

Next steps

Quickstart

Configuration

Deployment

Architecture

​Prerequisites

​Check installed versions

​Install Elixir and Erlang

​Install Node.js

​Local installation (recommended)

​Docker installation

​Using the convenience script

​Manual Docker build and run

​Docker Compose (production)

​Configuration

​Profiles

​Environment variables

​Create a custom profile

​Multi-node deployment (clustering)

​Troubleshooting

​Port already in use

​Mix not found

​Compilation errors

​Docker build failures

​Profile not loading

​Next steps

Quickstart

Configuration

Deployment

Architecture

Prerequisites

Check installed versions

Install Elixir and Erlang

Install Node.js

Local installation (recommended)

Docker installation

Using the convenience script

Manual Docker build and run

Docker Compose (production)

Configuration

Profiles

Environment variables

Create a custom profile

Multi-node deployment (clustering)

Troubleshooting

Port already in use

Mix not found

Compilation errors

Docker build failures

Profile not loading

Next steps