Skip to main content
The example below installs the v0.8.0 container. Its image digest and verification reports are on versions and evidence. The primary distribution is ghcr.io/jaxernst/lasso-rpc, with native Linux AMD64 and ARM64 images. Use the Compose attachment from the release you select. It requires Docker Compose and OpenSSL for generating local secrets:
Open http://localhost:4000/dashboard. Preserve .env across restarts and keep it private; it contains the signing and Erlang distribution secrets. Compose passes its values into the container, including provider credentials you add. Changing .env requires container recreation with docker compose up -d --force-recreate --wait; reloading YAML does not change a running container’s environment. Compose binds port 4000 to localhost, runs as UID/GID 10001:10001, and keeps the root filesystem read-only. /tmp is temporary; the named /data volume retains profiles and benchmark history. docker compose down retains that volume; docker compose down --volumes deletes it. Set LASSO_PORT in .env to choose another local port and LASSO_NODE_ID to give the instance a stable identity.

Verify or pin the image

Completed container publication attaches container-release.json, native verification reports, and container-verification.md with its immutable image digest. Version tags are never replaced with different contents. For a digest-pinned installation, set this in .env, using the digest from the selected release:
Then run docker compose pull and docker compose up -d --wait. To verify the signed publication attestation, install the GitHub CLI and run:
The signed attestation identifies the publication workflow. Platform BuildKit provenance records the pinned public source used for the build; the index also contains SBOMs. Source and publication-tooling revisions are recorded separately in container-release.json. See Releasing for the verification scope, first-publication access setup, and retry behavior.

Custom profiles and credentials

An empty data volume is seeded with bundled profiles in /data/config/profiles. Existing files are preserved on restart and upgrade. Benchmark snapshots use /data/benchmark_snapshots. To maintain profiles on the host, copy the starting configuration from the running container:
Create compose.override.yml next to compose.yml:
Edit the YAML in profiles/, retaining a valid public.yml. Additional profiles need matching filenames and frontmatter slugs. See Configuration for supported settings. Files must be readable by UID 10001 and directories traversable by that UID; host directories used for writable history must also be writable by UID 10001. Keep credential values in .env and reference them as ${VARIABLE_NAME} in provider URLs or headers. Apply mount changes or environment changes:
For new profiles and YAML-only edits, validate and reload the running node instead. New profiles reuse connected WebSocket upstreams:
Both commands exit nonzero on an invalid file, and a rejected reload keeps the active configuration. A successful reload prints :ok. A rejected reload reports its error and keeps the active configuration. Fix the file before restarting: a cold start cannot recover the prior in-memory configuration. Invalid files are logged during startup retries and prevent the service becoming ready. Use docker compose logs lasso to see the specific rejected field. A read-only mount supports loading and reloading; application-side configuration saves need a writable mount. LASSO_PROFILES_DIR overrides profile seeding and selection. LASSO_SNAPSHOTS_DIR independently overrides the history directory at runtime.

Upgrade and rollback

  1. Preserve .env and back up profiles and any history you need. For the default volume layout, docker compose cp lasso:/data/config/profiles ./profiles-backup and docker compose cp lasso:/data/benchmark_snapshots ./history-backup copy them out of the running container.
  2. Read the target release’s compatibility notes. Select its exact image tag or digest using LASSO_IMAGE in .env, and retain the previous value for rollback.
  3. Run docker compose pull, then docker compose up -d --wait. Check health, an upstream-backed RPC request, and the dashboard.
  4. Existing volume profiles are not replaced by newer bundled defaults. Compare provider changes with the target release’s example profiles and merge them deliberately. YAML validation rejects unknown settings; check custom profiles before an upgrade rather than relying on formerly ignored options.
  5. To roll back, restore the previous LASSO_IMAGE, pull, and recreate the container with the same environment. If the release changed the storage format, restore the matching backup according to its compatibility notes.
Do not run down --volumes as an upgrade step. Upgrading from v0.7.x to v0.8.0 needs no profile, journal or history migration; secrets and data carry over. Before you switch:
  • A profile without a transactions block keeps ordinary routing for eth_sendRawTransaction; the new transaction providers block is opt-in.
  • Opt-in execution_safety metadata now has four values: replay_safe, raw_transaction_broadcast, subscription and unknown. Update anything that matched on removed values.
For upgrades from v0.6.0 or earlier, also review the v0.7.0 changes:
  • Learned method refusals, historical depth and log-span limits now change provider order by default. Set all three provider-knowledge mode variables to off and recreate the container to keep v0.6.0 ordering.
  • Capability list fields left as YAML null now fail validation. Use [] for empty unsupported_methods, unsupported_categories and limits.block_age_methods. Validate custom profiles before upgrading.
For upgrades from v0.5.1 or earlier, also review the v0.6.0 changes:
  • Rename LW_BETA to BALANCED_FAST_BETA if you set it. v0.6.0 doesn’t read the old name.
  • Bare /api/ready now reports replica readiness only. Point load balancers that need upstream-backed readiness at /api/ready?profile=PROFILE&chain=CHAIN.
  • latency-weighted URLs and strategy values keep working as aliases of balanced-fast; metadata and logs report balanced_fast.
  • If you enrolled global block publication, rolling back needs a compatible binary or the coordinated disable procedure.
Images built before the persistent /data layout used /app/config/profiles and /app/priv/benchmark_snapshots. Copy customized configuration and history out of the old container before replacing it; a new empty volume cannot recover files from a deleted container. Restore the profiles into a readable host mount and the history into the new data volume, with ownership suitable for UID/GID 10001:10001. Keep the old container/data and backups until the new deployment passes verification.

Building locally

The source repository’s compose.yml builds from its checkout. From the selected Git tag, set SECRET_KEY_BASE and run docker compose up --build -d. Its local image is lasso-rpc:local; the downloadable Compose attachment uses the registry image instead. The foreground helper ./run-docker.sh also builds locally and persists data in its own lasso-rpc-data volume. These source-build paths are useful for development or independently rebuilding a release.