Minimal local Canton stack for developer workflows.
Canton is the blockchain network; Splice is the application stack that runs on it and ships a ready-made LocalNet — a set of Docker Compose files for running a whole Canton network on your machine.
Splice LocalNet is powerful but has many moving parts and knobs. This tool is a thin wrapper around it: you get a single small config file and a handful of commands (init, start, stop, ...), and it takes care of downloading Splice, translating your config into the right Docker Compose invocation, and running it. It does not fork or copy Splice — it fetches a pinned version and drives it as-is.
- Node.js 22+
- Git
- Docker Compose v2
npx @bootnodedev/canton-barebones init # scaffold the config file into the current folder (run once)
npx @bootnodedev/canton-barebones start # download Splice if needed, then start the stacknpx pulls the runtime dependencies automatically, so there is no separate install step.
The tool is also published as a dpm component
(a self-contained binary — no Node required). Both flows below need a project with a
daml.yaml and end in the same state: the component listed in daml.yaml and installed.
Add it with one command:
dpm add component oci://ghcr.io/bootnodedev/canton-barebones:latest # or pin a versionOr declare it under components in daml.yaml and install (e.g. when the entry is
already committed to the project):
# daml.yamlcomponents:
- oci://ghcr.io/bootnodedev/canton-barebones:latestdpm install packageOnce installed, the CLI is available as a dpm subcommand:
dpm canton-barebones init # `dpm cbn <cmd>` works too
dpm canton-barebones startEvery command in the CLI reference works the same way, prefixed with
dpm canton-barebones (or the dpm cbn alias).
npm install # install dependencies (run once)
npm run init # scaffold the config file into your project (run once)
npm run start # download Splice if needed, then start the stackThere are two locations to keep in mind (see src/paths.js):
- the package — where this tool is installed; holds the bundled default files.
- the project — the folder you run commands from; holds your config, your overrides, and everything under
.generated/.
The lifecycle:
npm run init
└─ copies bundled templates into your project (once):
canton-barebones.config.json ← the stack config you edit
splice-localnet-overrides.yaml ← local Docker Compose tweaks
npm run start (and status / logs / validate — anything that reads config)
└─ loadConfig() (src/config.js) reads + validates your config
├─ ensureSpliceCheckout() (src/splice.js) downloads Splice on first run
└─ runDockerCompose() (src/compose.js) generates runtime files, runs compose
init only copies files. Nothing is downloaded and nothing runs until start (or any other config-reading command).
Created lazily by the first command that reads your config (not by init). It is disposable and git-ignored — delete it and it is rebuilt on the next start.
| Path | Written by | What it is |
|---|---|---|
.generated/splice/<repo>/<tag>/…/localnet/ | src/splice.js | the downloaded Splice LocalNet files for the pinned version |
.generated/localnet.env | src/compose.js | environment values that pass your config into Splice's compose files |
.generated/empty.env | src/compose.js | an empty placeholder some compose files expect |
Run npm run init once to scaffold canton-barebones.config.json, then edit it. The scaffolded default is a minimal working stack: the SV plus the appUser validator running headless (its backend, no UIs); appProvider and all tools are off. You turn things on as you need them.
A Canton network here has three kinds of pieces:
- SV (Super Validator) — the node that runs the global synchronizer, the shared backbone all participants connect to. It is required infrastructure, so its backend always runs; only its web dashboards are configurable (the
svflags). - Validators — the participant nodes that run your apps. Splice's LocalNet ships two fixed slots,
appProviderandappUser. Each hasenabled(run its backend) andui(also expose its web UIs). - Network tools — utilities that work across the nodes: the Canton
console,multiSync(adds a second, local synchronizer), andswaggerUI(API docs).
Rules:
uineeds the backend, so it can only betruewhen that validator'senabledistrue.- A validator's UIs come as one bundle (wallet + ANS): it is on-or-off per validator, not per individual UI.
enabled: true, ui: falseruns it headless — backend only, reached on its direct API ports. - The SV backend is not configurable — it is required infrastructure and always runs. Its web UIs are, individually: an
svflag off skips that UI container, while the API routes on the SV's nginx port keep working (a disabled UI's URL answers 502). - Config changes take effect on the next
start.
src/compose.js translates the config into the Docker Compose invocation (see the module comment there for detail). Splice wires nginx to route to each participant's UIs as fixed upstreams and refuses to start if one is missing, which shapes the levers:
| Config | Effect |
|---|---|
| always | --profile sv runs the SV fully and, with it, the shared postgres/canton/splice/nginx |
validators.*.enabled | switches that validator's backend on/off via an env var |
validators.*.ui | on → also starts that validator's UIs; off (but enabled) → an env var blanks its nginx routes so it runs headless |
an sv UI flag off | env vars pin that UI to 0 replicas and alias its hostname onto nginx |
a networkTools flag on | starts that tool via its profile |
So the default config launches the SV plus a headless appUser, and each flag you flip adds more. (For why a headless validator needs special handling, see Design notes.)
Assuming every flag is on, this is everything the stack exposes. Each participant gets its own nginx port (sv 4000, app-provider 3000, app-user 2000), and its web UIs and ledger APIs are reached through hostnames on that port. A validator's routes only appear when its ui: true; the SV's APIs are always on and its web UIs follow the sv flags. All *.localhost names resolve to 127.0.0.1 automatically.
In headless mode (
enabled: true, ui: false) a validator's nginx routes below are not exposed. Reach its ledger API on the direct participant ports instead: JSON on<prefix>975, gRPC on<prefix>901, where the prefix is2/3/4— e.g.localhost:2975(JSON) andlocalhost:2901(gRPC) for app-user.
The three web UIs each have an sv config flag; turning one off makes its URL answer 502 while the API rows keep working.
| Surface | URL | Requires |
|---|---|---|
| SV operations dashboard | http://sv.localhost:4000 | sv.svUI |
| Scan (network explorer) | http://scan.localhost:4000 | sv.scanUI |
| Wallet | http://wallet.localhost:4000 | sv.walletUI |
| JSON Ledger API | http://canton.localhost:4000/v2 | always |
| OpenAPI spec | http://canton.localhost:4000/docs/openapi | always |
| Surface | URL |
|---|---|
| Wallet | http://wallet.localhost:2000 |
| ANS (name service) | http://ans.localhost:2000 |
| JSON Ledger API | http://json-ledger-api.localhost:2000 (or http://canton.localhost:2000) |
| gRPC Ledger API | grpc-ledger-api.localhost:2000 (http2) |
| OpenAPI spec | http://canton.localhost:2000/docs/openapi |
| Surface | URL |
|---|---|
| Wallet | http://wallet.localhost:3000 |
| ANS (name service) | http://ans.localhost:3000 |
| JSON Ledger API | http://json-ledger-api.localhost:3000 (or http://canton.localhost:3000) |
| gRPC Ledger API | grpc-ledger-api.localhost:3000 (http2) |
| OpenAPI spec | http://canton.localhost:3000/docs/openapi |
| Tool | URL / access | Requires |
|---|---|---|
| Swagger UI (aggregated API docs) | http://localhost:9090 | networkTools.swaggerUI |
| Canton console | interactive container, no web UI (docker attach console) | networkTools.console |
| Multi-sync | no UI (adds a second local synchronizer) | networkTools.multiSync |
The binary is canton-barebones <command>; the npm run <command> scripts wrap it. To pass a flag through npm, add -- first (e.g. npm run validate -- --json).
| Command | What it does | Side effects | Docker |
|---|---|---|---|
init [--force] | Scaffold the config and compose override into the project | Writes canton-barebones.config.json and splice-localnet-overrides.yaml (existing files are skipped unless --force) | no |
setup | Download the pinned Splice LocalNet source | Writes .generated/splice/… on first run | no |
validate | Validate the config and resolved Splice paths | Writes .generated/localnet.env; downloads Splice on first run | no |
start | Start the stack (docker compose up -d) | Starts containers, creates volumes and the Docker network | yes |
stop | Stop containers, keep volumes (docker compose down) | Removes containers; data volumes are preserved | yes |
reset | Stop containers and remove volumes (docker compose down -v) | Deletes all stack data | yes |
status | Show service status (docker compose ps) | none | yes |
logs [args…] | Show logs (docker compose logs); extra args pass through | none | yes |
compose <args…> | Run docker compose with the configured LocalNet files; no args prints the computed docker command (dry run) | depends on the args | yes |
stop works even with a broken config. It only reads composeProjectName, which is all Docker Compose needs to find the stack's containers (it matches them by project label). If that field is missing or invalid, stop fails with the usual config error. Every other Docker command validates the full config first.
Exit codes & output. Every command exits 0 on success and 1 on failure, printing the error message to stderr.
--json (on validate, setup, status) switches to machine-readable output: success goes to stdout, and on failure a { "ok": false, "error": "…" } object goes to stderr, still exiting 1. Use validate --json to see exactly what a config resolves to without starting anything — its plan field lists the compose profiles, headless validators, disabled SV UIs, and participant env:
canton-barebones validate --json
# { "ok": true, "plan": { "upProfiles": ["sv","app-user"], "headlessValidators": [], "disabledSvUIs": [], "nodeEnv": {…} }, … }
canton-barebones status --json # one JSON object per service, straight from docker composestatus (or status --json) shows containers, but a container being up is not the same as a participant serving. To confirm a participant's backend is actually live, hit its readyz — the same probe Splice uses internally. Each participant has a port prefix: 2 app-user, 3 app-provider, 4 sv.
curl -sf http://localhost:2903/api/validator/readyz &&echo"app-user ready"# 3903 = app-provider, 4903 = sv
docker exec splice ls /app/app-user/ # → "on" when that participant is activeFor UIs, request them through nginx by hostname (see UIs and endpoints), e.g. curl -sI -H 'Host: wallet.localhost' http://localhost:2000/.
Non-obvious behaviors worth knowing before automating against the stack:
- No per-validator backend container. The
sv,app-provider, andapp-userbackends are multiplexed into the sharedcantonandsplicecontainers, selected by the*_PROFILEenv vars — not separate containers. Only the UIs and network tools run as their own containers, sodocker psnever shows anapp-userservice. - Ports are published statically. Each participant's ports (prefix
2/3/4) are always bound while the shared containers run, even for disabled participants. A bound port does not mean something is answering — usereadyzas the source of truth. - UIs go through nginx, published on ports
2000/3000/4000, not as per-UI host ports.*.localhosthostnames resolve to127.0.0.1automatically. - Config changes apply on the next
start— nothing reacts to the file while the stack is running.
| Symptom | Cause | Fix |
|---|---|---|
Config version N is not compatible … | The config predates the current schema | init --force to get the new defaults, then re-apply your edits |
Invalid canton-barebones.config.json: … | A field is missing, mistyped, or the wrong type (the message names the path) | Fix the named field and re-run |
docker is required to run the stack | Docker is not installed or not running | Install / start Docker, then retry |
Port already in use (e.g. 2000, 4903, 5432) | Another stack (or the same one) is already up on that port | stop the running stack, or free the port |
| Containers are up but a participant does not respond | A bound port is not the same as a live backend | Check readyz (see Verifying the stack) |
| Stale or corrupted state after config churn | Volumes hold old data | reset to wipe volumes, then start |
Anything under .generated/ looks wrong | It is disposable | Delete .generated/ — it is rebuilt on the next start |
| File | Responsibility |
|---|---|
bin/canton-barebones.js | CLI entry point: parses the command and --json, dispatches to src/* |
src/config.js | Loads and zod-validates the config; resolves runtime paths and the pinned Splice checkout |
src/compose.js | Turns the config into the Docker Compose invocation (profiles, env vars, override chain) and runs it |
src/splice.js | Downloads and pins the Splice LocalNet source into .generated/ |
src/init.js | Scaffolds the bundled templates into the project (init) |
src/output.js | Centralizes CLI output: human text vs --json, stdout vs stderr |
src/paths.js | Resolves paths against the package (bundled files) vs the project (your files) |
| Command | What it runs | Needs Docker |
|---|---|---|
npm test | Unit tests (node --test over scripts/**/*.test.js) — config schema validation and the runtime plan | no |
npm run test:e2e | Smoke test (scripts/smoke.js) — resolves the default config (SV + headless appUser) and drives a valid compose model | yes (+ a Splice checkout) |
Run npm test for a fast check without Docker; run npm run test:e2e to exercise the full compose model end to end.
Versioning and npm publishing are automated with Changesets. You never bump the version or run npm publish by hand.
| Command | What it does | Who runs it |
|---|---|---|
npm run changeset | Interactive CLI: asks the bump type (patch/minor/major) and a summary, writes .changeset/*.md | you, in your branch |
npm run release | changeset publish — publishes bumped packages to npm and creates git tags | CI only (release.yml) |
End-to-end flow:
- Make your change in a branch. Before opening the PR, run
npm run changesetand commit the generated.changeset/*.mdalongside your code. It records what kind of release your change is — not the version number.- A PR that doesn't affect the published package (docs, CI, chores) still needs one: run
npx changeset --empty. Thechangeset-checkworkflow fails a PR that has no changeset.
- A PR that doesn't affect the published package (docs, CI, chores) still needs one: run
- Merge the PR to
main. This does not publish anything. The version stays put. - A bot opens a "Version Packages" PR (via
release.yml). It consumes the pending changesets, bumps the version inpackage.json, and updatesCHANGELOG.md. It keeps this PR up to date as more changesets land onmain. - Merge the "Version Packages" PR when you want to cut a release. That merge triggers
release.ymlto runnpm run release, publishing to npm with provenance and creating the git tag.
In short: changesets accumulate on main without publishing; you publish by merging the bot's Version Packages PR. Batch several changes into one release, or ship them one at a time.
Deeper mechanics, not needed for day-to-day use.
Running a validator with its backend on but its UIs off (enabled: true, ui: false) needs a small trick, because Splice couples the two through nginx:
- The nginx image renders every
/etc/nginx/templates/*.templatefile into/etc/nginx/conf.d/at startup. - Splice mounts each validator's routing config there (e.g.
app-user.conf→/etc/nginx/templates/app-user.conf.template). That config proxies to the validator's UI containers as fixed upstreams, and nginx refuses to start if an upstream host does not exist. - Because the validator's backend is on, Splice renders its nginx config — so nginx would look for UI containers that we did not start, and crash.
CantonBarebones works around this without editing any Splice file and without generating YAML. Docker Compose deduplicates volume mounts by their target path, and the later -f wins. The static override shipped inside the package (templates/runtime-overrides.yaml, always applied after Splice's files) mounts an env-var-selected source file over that exact template path:
Splice: conf/nginx/app-user.conf → /etc/nginx/templates/app-user.conf.template
Static override: ${APP_USER_NGINX_ROUTES} → /etc/nginx/templates/app-user.conf.template ← wins
ui: true → the var points at Splice's own app-user.conf → identical routes, nothing changes.
ui: false → it points at an empty file in .generated/ → nginx renders no routes → starts fine.
The wrapper only writes the APP_*_NGINX_ROUTES env vars to .generated/localnet.env. The validator's backend still runs (it is driven by an env var, not nginx) and stays reachable on its direct API ports; only its web routing is dropped. See templates/runtime-overrides.yaml and writeLocalnetEnv in src/compose.js for the full detail.
Turning off an SV web UI (sv.scanUI / sv.svUI / sv.walletUI) cannot reuse the empty-template trick above: Splice's sv.conf mixes the UI routes with API routes (scan API, SV admin API, canton JSON API) that proxy to the always-running splice/canton containers and must stay up, and the flags are per-UI rather than all-or-nothing. The same static override uses two other compose levers instead, also driven by env vars from .generated/localnet.env:
deploy.replicas: ${…_REPLICAS}—0for a disabled UI, so compose never starts its container. (An override entry rather thandocker compose --scale, which errors for services whose profile is not selected.)- nginx still resolves that UI's hostname at startup (
proxy_pass http://scan-web-ui:8080/…) and would crash with "host not found in upstream" once no container owns the name. So nginx carries a network alias per UI whose value comes from${…_NGINX_ALIAS}: for a disabled UI it is the real hostname — the name resolves onto the nginx container itself, nginx boots, and since nothing there listens on the UI port, browsing the disabled UI answers 502 while every API route on port 4000 keeps working. For an enabled UI it is an inert<name>-unused(static YAML has no conditionals, so the list entry always exists and only its value changes).
{ "version": 1, "splice": { "repo": "canton-network/splice", "tag": "0.6.11" }, // which Splice version to download"composeProjectName": "canton-barebones", // Docker Compose project name"dockerNetwork": "cantonBarebones", // Docker network name"persistence": { "mode": "persistent" }, // "persistent" keeps volumes; "ephemeral" wipes on reset"validators": { "appProvider": { "enabled": false, "ui": false }, // enabled = backend; ui = also show its web UIs"appUser": { "enabled": true, "ui": false }, // default: backend on, UIs off (headless) }, "sv": { "scanUI": true, "svUI": true, "walletUI": true }, // the SV's web UIs, toggleable per UI"networkTools": { "console": false, "multiSync": false, "swaggerUI": false }, }