Skip to main content
The example below installs the verified v0.5.0 container. See release evidence for its image digest and native installation checks. 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:
In v0.5.0, new profiles can reuse connected WebSocket upstreams after reload. If you remain on v0.3.4, recreate the container after adding profiles to avoid unavailable subscriptions. For new profiles and YAML-only edits in v0.5.0, reload the running node:
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. When migrating the v0.3.3 example profiles to v0.3.4, remove the ignored provider fields type and api_key_required. Replace the old adapter_config.max_block_range with capabilities.limits.max_block_range. Preserve your own provider URLs, credentials, and supported settings. The target release’s bundled profiles show the supported shape. 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.