diff --git a/docs/getting-started.md b/docs/getting-started.md index e0f4b253..5f38da3b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,9 +4,9 @@ Canton DevKit is a single Go binary that orchestrates the Splice LocalNet Docker stack. It ships two ways: 1. **DPM component** (primary) — install through the Daml Package - Manager and invoke as `dpm localnet `. + Manager and invoke as `dpm localnet `. 2. **Standalone binary** (`canton-devkit`) — a self-contained - executable for users who don't run DPM (CI, DevOps, workshop + executable for users who don't run DPM (CI, DevOps, workshop facilitators), shipped as release archives. Invoke as `canton-devkit localnet `. @@ -19,14 +19,18 @@ tree**. Throughout the docs, `dpm localnet ` and > never changes host permissions. It orchestrates the existing Splice > LocalNet container stack. + + ## 1. Prerequisites -| Requirement | Why | Check | -|---|---|---| -| Docker Engine / Desktop | DevKit runs LocalNet as containers | `docker version` | -| Docker Compose **v2** | LocalNet is a compose project | `docker compose version` | -| ~8 GB free RAM for Docker | Splice stack is memory-hungry | Docker Desktop → Settings → Resources | -| ~20 GB free disk | Splice images + volumes | `df -h` | + +| Requirement | Why | Check | +| ------------------------- | ---------------------------------- | ------------------------------------- | +| Docker Engine / Desktop | DevKit runs LocalNet as containers | `docker version` | +| Docker Compose **v2** | LocalNet is a compose project | `docker compose version` | +| ~8 GB free RAM for Docker | Splice stack is memory-hungry | Docker Desktop → Settings → Resources | +| ~20 GB free disk | Splice images + volumes | `df -h` | + Run the built-in host check at any time — it never modifies anything: @@ -89,6 +93,7 @@ contains the `canton-devkit` binary plus `LICENSE` and `README.md`. Every release also publishes a single `SHA256SUMS` file covering all archives. ### Quick install (macOS arm64 / Linux amd64) + ```bash curl -fsSL https://raw.githubusercontent.com/bitdynamics-ab/canton-devkit/main/install.sh | sh ``` @@ -119,6 +124,8 @@ Supported platforms: - macOS Apple Silicon (`darwin/arm64`) - Linux x86_64 (`linux/amd64`) + + ### Homebrew (macOS arm64 / Linux amd64) ```bash @@ -126,11 +133,11 @@ brew tap bitdynamics-ab/canton-devkit brew install bitdynamics-ab/canton-devkit/canton-devkit ``` -To upgrade after a new release is published: +To upgrade after a new release is published, refresh the tap and then +upgrade the formula: ```bash -brew update -brew upgrade canton-devkit +brew update && brew upgrade canton-devkit ``` The formula downloads platform-specific release tarballs from this @@ -146,6 +153,8 @@ the tap only hosts the Homebrew formula. > `/etc/apt/sources.list.d/canton-devkit.list`, remove that file and use > the quick-install script, a release tarball, or Homebrew instead. + + ### Manual download — macOS (Apple Silicon) Download the binary for your platform from the @@ -168,6 +177,8 @@ xattr -d com.apple.quarantine /usr/local/bin/canton-devkit 2>/dev/null || true canton-devkit version ``` + + ### Manual download — Linux (amd64) ```bash @@ -183,6 +194,8 @@ sudo mv canton-devkit /usr/local/bin/ canton-devkit version ``` + + ### Windows (amd64, PowerShell) ```powershell @@ -221,15 +234,21 @@ the WSL 2 backend. go install github.com/bitdynamics-ab/canton-devkit/cmd/canton-devkit@latest ``` + + ## 4. Compatibility matrix + + ### Platforms (released, tested) -| OS | Arch | Status | -|---|---|---| -| macOS | arm64 (Apple Silicon) | ✅ Supported | -| Linux | amd64 | ✅ Supported | -| Windows | amd64 | ✅ Supported | + +| OS | Arch | Status | +| ------- | --------------------- | ----------- | +| macOS | arm64 (Apple Silicon) | ✅ Supported | +| Linux | amd64 | ✅ Supported | +| Windows | amd64 | ✅ Supported | + Other OS/arch combinations may work (DevKit only orchestrates Docker) but are untested — `localnet doctor` prints a warning on unsupported @@ -237,8 +256,7 @@ platforms. ### Splice LocalNet versions -DevKit pins a catalogue of tested Splice versions; `localnet up ---version ` selects one. List them at runtime: +DevKit pins a catalogue of tested Splice versions; `localnet up --version ` selects one. List them at runtime: ```bash canton-devkit localnet versions @@ -250,15 +268,17 @@ at your own risk via `up --version --allow-uncurated`. ## 5. Troubleshooting the install -| Symptom | Cause | Fix | -|---|---|---| -| `doctor` says **Docker daemon** ✗ | Docker not running | Start Docker Desktop / `sudo systemctl start docker` | -| `doctor` says **Compose v2** ✗ | Only Compose v1 present | Upgrade to Docker Compose v2 (`docker compose`, not `docker-compose`) | -| `up` fails **PORTS_IN_USE** | Another process holds a port | Stop the conflicting process, or use a different `--name` | -| `up` hangs at "waiting for healthy" | Insufficient Docker memory | Raise Docker memory to ≥ 8 GB; see [Known limitations](limitations.md) | -| Linux: `permission denied` on the Docker socket | User not in `docker` group | `sudo usermod -aG docker $USER` then re-login | -| macOS: "cannot be opened because the developer cannot be verified" | Gatekeeper quarantine | `xattr -d com.apple.quarantine $(which canton-devkit)` | -| Web UI / Explorer shows stale ports after a restart | Docker re-assigned ephemeral ports | DevKit re-captures them within ~15 s; or run `localnet restart --name ` | + +| Symptom | Cause | Fix | +| ------------------------------------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------- | +| `doctor` says **Docker daemon** ✗ | Docker not running | Start Docker Desktop / `sudo systemctl start docker` | +| `doctor` says **Compose v2** ✗ | Only Compose v1 present | Upgrade to Docker Compose v2 (`docker compose`, not `docker-compose`) | +| `up` fails **PORTS_IN_USE** | Another process holds a port | Stop the conflicting process, or use a different `--name` | +| `up` hangs at "waiting for healthy" | Insufficient Docker memory | Raise Docker memory to ≥ 8 GB; see [Known limitations](limitations.md) | +| Linux: `permission denied` on the Docker socket | User not in `docker` group | `sudo usermod -aG docker $USER` then re-login | +| macOS: "cannot be opened because the developer cannot be verified" | Gatekeeper quarantine | `xattr -d com.apple.quarantine $(which canton-devkit)` | +| Web UI / Explorer shows stale ports after a restart | Docker re-assigned ephemeral ports | DevKit re-captures them within ~15 s; or run `localnet restart --name ` | + For anything else, attach the full `localnet doctor` output to a [GitHub issue](https://github.com/bitdynamics-ab/canton-devkit/issues) — @@ -267,9 +287,10 @@ it includes OS/arch, Docker/Compose versions, and the check results. ## 6. Next steps - [HackCanton Season 3 starter](hackcanton-s3.md) — install, one - working example, and the breaks that eat day-one time. +working example, and the breaks that eat day-one time. - [LocalNet lifecycle](localnet-lifecycle.md) — zero to a running - LocalNet, multiple instances, deterministic ports, and clean-up. +LocalNet, multiple instances, deterministic ports, and clean-up. - [Tokens](tokens.md) — CIP-0112 token flows on LocalNet. - [Explorer](explorer.md) — browse the Active Contract Set and - recent transactions from the Web UI. +recent transactions from the Web UI. + diff --git a/docs/homebrew.md b/docs/homebrew.md index 45867f88..844ef875 100644 --- a/docs/homebrew.md +++ b/docs/homebrew.md @@ -31,13 +31,43 @@ brew install bitdynamics-ab/canton-devkit/canton-devkit ## Upgrade -After a new release is published and the formula is updated: +Homebrew separates refreshing formula metadata from installing a newer +binary: + +- `brew update` — pulls the latest formula from this tap (and other taps) +- `brew upgrade canton-devkit` — installs a newer release when the + formula version is ahead of what you have installed + +`brew update` does not take a formula name. Passing one (for example +`brew update canton-devkit`) does not upgrade the package; Homebrew may +remap that to `brew upgrade`, but only against whatever formula version +your local tap already has. + +After a new release is published: ```sh brew update brew upgrade canton-devkit ``` +Or as one line: + +```sh +brew update && brew upgrade canton-devkit +``` + +`brew upgrade canton-devkit` alone is often enough, because Homebrew may +auto-refresh taps before upgrading. If it reports the installed version +is already current right after a new release, run `brew update` first, +then `brew upgrade canton-devkit` again. + +Confirm the installed version: + +```sh +canton-devkit version +brew info canton-devkit +``` + ## How the formula stays in sync This is **automatic** on every release tag (`v*`). `.github/workflows/release.yml`: diff --git a/website/docs-map.mjs b/website/docs-map.mjs index 3f4aa0b9..a0c86247 100644 --- a/website/docs-map.mjs +++ b/website/docs-map.mjs @@ -22,7 +22,7 @@ export const docsMap = [ { src: 'observability.md', dest: 'guides/observability', description: 'Enable the observability profile for Prometheus + Grafana, understand the live Splice metric naming convention, and toggle the sidecars at runtime.' }, { src: 'dashboard-customization.md', dest: 'guides/dashboard-customization', description: 'Extend, replace, or restore the bundled Grafana dashboard for a running LocalNet — panels, template variables, and persistence across down/up cycles.' }, { src: 'tokens.md', dest: 'guides/tokens', description: 'Work with Canton Token Standard instruments on a live LocalNet — CIP-0056 assets and Token Standard V2 (CIP-0112) — from the CLI or the Web UI.' }, - { src: 'homebrew.md', dest: 'guides/homebrew', description: 'Install canton-devkit via the Homebrew tap or direct formula, and how the formula is kept in sync on every release.' }, + { src: 'homebrew.md', dest: 'guides/homebrew', description: 'Install and upgrade canton-devkit via the Homebrew tap, and how the formula is kept in sync on every release.' }, { src: 'faq.md', dest: 'reference/faq', description: 'Common questions about canton-devkit: what it is, how the CLI and Web UI relate, versions, and day-to-day usage.' }, { src: 'versions.md', dest: 'reference/versions', description: 'How DevKit pins tested Splice LocalNet versions by commit SHA and content hash, discovers upstream tags, and resolves uncurated versions on opt-in.' }, { src: 'packaging.md', dest: 'reference/packaging', description: 'How canton-devkit ships — standalone binaries, the DPM component, and the Homebrew tap — and the current supply-chain integrity story.' },