diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json index d80b4be..7bff63d 100644 --- a/docs/pages/_meta.json +++ b/docs/pages/_meta.json @@ -15,6 +15,7 @@ "mcp-integration": "MCP Integration", "commands": "Yaci CLI Commands", "node-configuration": "Node Configuration", + "user-settings": "User Settings", "multi-node-setup": "Multi-node setup", "rollback-testing": "Rollback Testing", "ci-integration": "CI/CD Integration", diff --git a/docs/pages/getting-started/_meta.json b/docs/pages/getting-started/_meta.json index f2c3726..78d3d5e 100644 --- a/docs/pages/getting-started/_meta.json +++ b/docs/pages/getting-started/_meta.json @@ -1,5 +1,6 @@ { "docker": "Docker Setup", - "zip": "Zip Setup", - "npm": "NPM Setup" + "zip": "Zip Setup", + "npm": "NPM Setup", + "homebrew": "Homebrew Setup" } \ No newline at end of file diff --git a/docs/pages/getting-started/homebrew.mdx b/docs/pages/getting-started/homebrew.mdx new file mode 100644 index 0000000..1364b1c --- /dev/null +++ b/docs/pages/getting-started/homebrew.mdx @@ -0,0 +1,117 @@ +import { Callout } from 'nextra/components' + +# Homebrew Setup + +The Homebrew distribution installs the native Yaci CLI and its configuration with `brew`, and keeps it up to date with `brew upgrade`. It provides the same `yaci-devkit` command as the [NPM distribution](/getting-started/npm), without needing Node.js. + +## Prerequisites + +### Supported Platforms + +1. **macOS 15 (Arm64) or later** +2. **Linux x86**: Tested on Ubuntu 22.04 and later ([Homebrew on Linux](https://docs.brew.sh/Homebrew-on-Linux)) + +### Requirements + +- **Homebrew**: [brew.sh](https://brew.sh) +- **Available ports**: Default ports should be free (3001, 8080, 10000) + +For Ogmios and Kupo, ensure ports 1337 and 1442 are also available if you plan to use these services. + +## Installation + +For latest stable version: +```bash +brew install bloxbean/tap/yaci-devkit +``` + +For latest beta version: +```bash +brew install bloxbean/tap/yaci-devkit-beta +``` + +Both formulas install the same `yaci-devkit` command, so install only one of them. To switch, uninstall the other first: + +```bash +brew uninstall yaci-devkit-beta +brew install bloxbean/tap/yaci-devkit +``` + +Check that the command comes from Homebrew: + +```bash +which yaci-devkit +``` + +It should print `/opt/homebrew/bin/yaci-devkit` on macOS or `/home/linuxbrew/.linuxbrew/bin/yaci-devkit` on Linux. + + +**Switching from NPM?** An NPM install also provides a `yaci-devkit` command, and an older `sudo npm install -g` puts it in `/usr/local/bin`, which usually comes before Homebrew on the `PATH`. Remove it first: + +```bash +npm uninstall -g @bloxbean/yaci-devkit +# for an install made with sudo: +sudo npm uninstall -g --prefix /usr/local @bloxbean/yaci-devkit +``` + +Devnets and downloaded components in `$HOME/.yaci-cli` are kept, and are used by the Homebrew install too. + + +### Upgrade + +```bash +brew update +brew upgrade yaci-devkit +``` + +### Uninstall + +```bash +brew uninstall yaci-devkit +``` + +This does not remove `$HOME/.yaci-cli` (devnets, downloaded components and `devkit.properties`). + +## Getting Started + +The `yaci-devkit` command takes the same options as with the NPM distribution: + +```bash +# Devnet with Cardano node only +yaci-devkit up + +# Devnet with Yaci Store (Blockfrost-compatible APIs) +yaci-devkit up --enable-yaci-store + +# Sub-second block time (200ms) +yaci-devkit up --enable-yaci-store --block-time 0.2 --slot-length 0.2 + +# Devnet with the interactive Yaci CLI prompt +yaci-devkit up --interactive +``` + +To see all supported options: +```bash +yaci-devkit up --help +``` + +See the [NPM Setup](/getting-started/npm#basic-usage) page for more examples, service URLs and CLI commands. + +Yaci Viewer is not included. Install it separately through NPM: see [Install Yaci Viewer](/getting-started/npm#step-2-install-yaci-viewer-optional). + +## Configuration + +The bundled `application.properties`, `node.properties` and `download.properties` are inside the Homebrew installation and are replaced on every upgrade. Put your settings in `$HOME/.yaci-cli/devkit.properties` instead: + +```properties +yaci.store.enabled=true +prometheus.port=12799 +``` + +See [User Settings](/user-settings) for details. + +## Next Steps + +- **Learn all commands**: Check out [Yaci CLI Commands](/commands) +- **CI/CD integration**: Set up [automated testing](/ci-integration) +- **Compare options**: Consider [Docker Setup](/getting-started/docker) for local development diff --git a/docs/pages/getting-started/npm.mdx b/docs/pages/getting-started/npm.mdx index e5283cb..d06ae2b 100644 --- a/docs/pages/getting-started/npm.mdx +++ b/docs/pages/getting-started/npm.mdx @@ -177,6 +177,10 @@ yaci-devkit up --port 3002 --interactive yaci-devkit up -e 30 --interactive ``` +## Configuration + +The bundled configuration files are inside the NPM package and are replaced on every upgrade. Put your own settings, for example `yaci.store.enabled=true` or `prometheus.port=12799`, in `$HOME/.yaci-cli/devkit.properties`. See [User Settings](/user-settings). + ## Yaci Viewer Setup ### Starting Yaci Viewer @@ -312,4 +316,4 @@ See [Known Issues](../known-issues#devnet-node-does-not-start-while-another-card - **Learn all commands**: Check out [Yaci CLI Commands](/commands) - **CI/CD integration**: Set up [automated testing](/ci-integration) -- **Compare options**: Consider [Docker Setup](/getting-started/docker) for local development +- **Compare options**: Consider [Docker Setup](/getting-started/docker) for local development, or [Homebrew Setup](/getting-started/homebrew) to install without Node.js diff --git a/docs/pages/getting-started/zip.mdx b/docs/pages/getting-started/zip.mdx index c5f6b82..725e7f3 100644 --- a/docs/pages/getting-started/zip.mdx +++ b/docs/pages/getting-started/zip.mdx @@ -15,10 +15,6 @@ The Zip distribution is perfect for: **Note**: Yaci Viewer is not included in the Zip distribution. To add viewer functionality, you can install Yaci Viewer separately through NPM. See the [NPM installation guide](/getting-started/npm#step-2-install-yaci-viewer-optional) for details. - -PV11-compatible Ogmios/Kupo binaries are currently published only as Linux x86_64 builds. On macOS arm64 native CLI, those specific Ogmios/Kupo defaults cannot run directly. Use Docker as a workaround, or set custom `ogmios.url` / `kupo.url` values when compatible native builds are available. - - ## Key Advantages - **Reduced Disk Space**: Requires less disk space than Docker, containing only the Yaci CLI binary and configuration files @@ -40,6 +36,8 @@ Yaci CLI is currently supported on: ```bash rm -rf $HOME/.yaci-cli ``` + +This also removes your [User Settings](/user-settings) file, `$HOME/.yaci-cli/devkit.properties`. Copy it somewhere else first if you have one. ## Installation @@ -173,6 +171,10 @@ yaci-cli:> create-node -o --block-time 5 --slot-length 5 --start The `config` folder contains three important configuration files: + +A new release comes with a new `config` folder. To keep your settings across upgrades, put them in `$HOME/.yaci-cli/devkit.properties` instead: it can hold any key from these three files and wins over them. See [User Settings](/user-settings). + + ### application.properties Main configuration file for Yaci CLI functionality. diff --git a/docs/pages/introduction.mdx b/docs/pages/introduction.mdx index 431034a..81669e3 100644 --- a/docs/pages/introduction.mdx +++ b/docs/pages/introduction.mdx @@ -35,7 +35,7 @@ The ZIP distribution includes only the Yaci CLI and allows selective downloading **Supported Environments:** - Linux x64 -- macOS arm64 +- macOS 15 (arm64) or later ### 3. NPM Distribution @@ -50,7 +50,18 @@ Supported environments include: Linux x64, MacOS arm64 **Supported Environments:** - Linux x64 -- macOS arm64 +- macOS 15 (arm64) or later + +### 4. Homebrew Distribution + +The Homebrew distribution installs the same native Yaci CLI and `yaci-devkit` command as the NPM distribution, through `brew`, without needing Node.js. + +- `brew install bloxbean/tap/yaci-devkit` +- Updates with `brew upgrade` + +**Supported Environments:** +- Linux x64 +- macOS 15 (arm64) or later ## Getting Started @@ -61,6 +72,7 @@ For the quickest setup experience, we recommend starting with the [Docker Setup] - [Docker Setup](/getting-started/docker) - Installation method - [Zip Setup](/getting-started/zip) - Non-Docker installation - [NPM Setup](/getting-started/npm) - NPM package installation +- [Homebrew Setup](/getting-started/homebrew) - Homebrew installation - [Yaci CLI Commands](/commands) - Learn about available CLI commands ## Important Notes diff --git a/docs/pages/known-issues.mdx b/docs/pages/known-issues.mdx index c36c234..5f3f20f 100644 --- a/docs/pages/known-issues.mdx +++ b/docs/pages/known-issues.mdx @@ -106,7 +106,7 @@ For technical details about this issue, see: [GitHub Issue #65](https://github.c ### Devnet node does not start while another cardano-node runs -Applies to the zip, npm and native/JAR distributions. Docker is not affected: the devnet node runs in the container's own network, and its Prometheus port is not published to the host. +Applies to the zip, npm, Homebrew and native/JAR distributions. Docker is not affected: the devnet node runs in the container's own network, and its Prometheus port is not published to the host. #### Current Behavior @@ -128,7 +128,8 @@ Stop the other node, or give the devnet a free port. The port is written into th |---|---|---| | Zip / native binary | `create-node -o --prometheus-port 12799` | `prometheus.port=12799` in `config/application.properties`, or `./yaci-cli -Dprometheus.port=12799` | | JAR | `create-node -o --prometheus-port 12799` | `java -Dprometheus.port=12799 -jar yaci-cli.jar` | -| NPM | `yaci-devkit up --prometheus-port 12799` | `PROMETHEUS_PORT=12799 yaci-devkit up` | +| NPM / Homebrew | `yaci-devkit up --prometheus-port 12799` | `PROMETHEUS_PORT=12799 yaci-devkit up` | +| Zip / NPM / Homebrew (v0.12.0+) | | `prometheus.port=12799` in `$HOME/.yaci-cli/devkit.properties` (see [User Settings](/user-settings)) | The `PROMETHEUS_PORT=12799` environment variable works with every distribution. Use one of the "Every time" forms if you also create devnets through the admin API or Yaci Viewer, which use the `prometheus.port` property. diff --git a/docs/pages/user-settings.mdx b/docs/pages/user-settings.mdx new file mode 100644 index 0000000..d482792 --- /dev/null +++ b/docs/pages/user-settings.mdx @@ -0,0 +1,58 @@ +import { Callout } from 'nextra/components' + +# User Settings (devkit.properties) + +`$HOME/.yaci-cli/devkit.properties` holds your own Yaci CLI settings. It is read by the [Homebrew](/getting-started/homebrew), [NPM](/getting-started/npm) and [Zip](/getting-started/zip) distributions, and is kept across upgrades: an upgrade replaces the bundled configuration files, but never this file. + + +Available from Yaci DevKit `v0.12.0`. The [Docker distribution](/getting-started/docker) does not read it: use its `config/env` and `config/node.properties` files instead. + + +## Create the file + +The file is optional. Create it when you need it: + +```bash +mkdir -p $HOME/.yaci-cli +nano $HOME/.yaci-cli/devkit.properties +``` + +It can hold any key from the bundled `application.properties`, `node.properties` or `download.properties`, in the same `key=value` format. For example: + +```properties +# Start Yaci Store with every devnet +yaci.store.enabled=true + +# Devnet node's Prometheus port, when another cardano-node on this machine uses 12798 +prometheus.port=12799 + +# Node mode (node.properties) +nodeMode=yano-only + +# Your own Plutus cost models (a folder with plutus-costmodels-v10.json and plutus-costmodels-v11.json) +yaci.cli.plutus-costmodels-path=/Users/me/cardano/costmodels +``` + +The settings are read when `yaci-devkit` (or `yaci-cli`) starts: restart it after changing the file. + +## Precedence + +From highest to lowest: + +1. Command options, such as `yaci-devkit up --prometheus-port 12799` or `create-node --block-time 2`, for that command +2. `-D` options, such as `yaci-devkit -Dprometheus.port=12799 up` or `./yaci-cli -Dprometheus.port=12799` +3. Environment variables, such as `PROMETHEUS_PORT=12799` or `YACI_STORE_ENABLED=true` +4. `$HOME/.yaci-cli/devkit.properties` +5. The bundled `application.properties`, `node.properties` and `download.properties` + +A setting in `devkit.properties` therefore wins over the same setting in the bundled files, including the `config` folder of the Zip distribution. + +The environment variable for a property is its name in upper case, with `.` replaced by `_` and `-` removed: `yaci.store.enabled` becomes `YACI_STORE_ENABLED`. + +## Things to know + +- **Location**: the file is always `$HOME/.yaci-cli/devkit.properties`, even when you set `yaci.cli.home` to store devnets and components elsewhere. +- **Devnet settings**: genesis and node settings (from `node.properties`, and properties such as `prometheus.port`) are written into the devnet when it is created. Re-create the devnet after changing them: `create-node -o`, or `yaci-devkit up` (which creates a new devnet). +- **Paths**: use absolute paths. A relative path resolves against the directory you run `yaci-devkit` or `yaci-cli` from. +- **Shared**: Homebrew, NPM and Zip installs on the same machine all use `$HOME/.yaci-cli`, so they share this file, as they share devnets and downloaded components. +- **Clean reinstall**: removing `$HOME/.yaci-cli` removes this file too. Copy it somewhere else first if you want to keep it.