Zip Setup

For users who prefer not to use Docker, the ZIP distribution contains only Yaci CLI and allows you to download and manage necessary components like Cardano Node, Ogmios, Kupo, and Yaci Store directly through the command line.

Overview

The Zip distribution is perfect for:

• Developers and system administrators: Quickly set up custom node or multi-node networks
• Users wanting more control: Easily manage compatible component versions and configurations
• Non-Docker environments: Environments where Docker is not available or preferred

Key Advantages

• Reduced Disk Space: Requires less disk space than Docker, containing only the Yaci CLI binary and configuration files
• Version Flexibility: Specify compatible versions of Cardano Node and other components directly in the download configuration
• Customizable Setup: Selectively enable components like Yaci Store, Ogmios, and Kupo to achieve the same functionality as the Docker distribution

Prerequisites

Supported Platforms

Yaci CLI is currently supported on:

1. Linux x86: Tested on Ubuntu 22.04 and later
2. macOS 14 (Arm64) or later

rm -rf $HOME/.yaci-cli

Installation

Step 1: Download and Extract

1. Download the latest Yaci CLI Zip file from the releases page (opens in a new tab)

   File name format: yaci-cli-<version>-<os>-<arch>.zip

   Examples:

   • Linux: yaci-cli-x.y.z-linux-X64.zip
   • macOS: yaci-cli-x.y.z-macos-ARM64.zip

2. Unzip the downloaded file

3. Navigate to the extracted folder where you'll find:

   • yaci-cli - The main executable binary
   • config/ - Configuration files directory

Step 2: macOS Setup (macOS users only)

On macOS, downloaded executables are quarantined by default. Remove the quarantine:

xattr -d com.apple.quarantine path/to/yaci-cli-distribution/yaci-cli

Replace path/to/yaci-cli-distribution with your actual path.

Getting Started

Step 1: Run Yaci CLI

Navigate to the extracted folder and run:

./yaci-cli

You'll see the Yaci CLI prompt: yaci-cli:>

Step 2: Download Required Components

The ZIP distribution doesn't include the necessary components for creating a devnet. Download them using:

yaci-cli:> download

This automatically downloads all required components for your platform:

• Cardano Node
• Ogmios
• Kupo
• Yaci Store

All components are downloaded to $HOME/.yaci-cli by default.

Download Options

Overwrite existing components:

yaci-cli:> download --overwrite

Download individual components:

yaci-cli:> download -c node
yaci-cli:> download -c ogmios
yaci-cli:> download -c kupo
yaci-cli:> download -c yaci-store

Step 3: Create Your First Devnet

Once components are downloaded, create and start a devnet:

yaci-cli:> create-node -o --start

This creates a new devnet with a single node and starts it with a 1-second block time.

yaci-cli:> enable-yaci-store    # Enable Yaci Store
yaci-cli:> enable-kupomios     # Enable both Ogmios and Kupo

Customize Block Time (Optional)

To create a devnet with custom block time:

# Sub-second block time (200ms)
yaci-cli:> create-node -o --block-time 0.2 --slot-length 0.2 --start
 
# Sub-second block time (100ms) with 80-slot epochs
yaci-cli:> create-node -o --block-time 0.1 --slot-length 0.1 --epoch-length 80 --start
 
# 5-second block time
yaci-cli:> create-node -o --block-time 5 --slot-length 5 --start

Important considerations:

• For sub-second block times, always set both --block-time and --slot-length
• The slot length must be equal to or less than the block time
• --epoch-length defines the number of slots per epoch (default: 600)
• With 0.1s slots and 80-slot epochs, each epoch lasts 8 seconds

Configuration

The config folder contains three important configuration files:

application.properties

Main configuration file for Yaci CLI functionality.

Enable Optional Components

By default, optional components are disabled. Enable them as needed:

ogmios.enabled=true
kupo.enabled=true
yaci.store.enabled=true

Update Ports

Customize default ports:

ogmios.port=1337
kupo.port=1442
yaci.store.port=8080

node.properties

Contains Cardano Node configuration. Update as needed to modify the node's genesis configuration.

download.properties

Contains default download versions for components. You can:

• Update versions for specific components
• Provide direct download URLs
• Control your environment with specific compatible versions

Basic Usage

Essential Commands

Once your devnet is running, you'll be in the "devnet:default" context:

Fund Test Addresses

devnet:default> topup <address> <ada_amount>

Check UTXOs

devnet:default> utxos <address>

Get Devnet Information

devnet:default> info

Reset Devnet Data

devnet:default> reset

Stop Devnet

devnet:default> stop

Advanced Configuration

Enable Services Before Creating Devnet

yaci-cli:> enable-yaci-store   # Enable Yaci Store
yaci-cli:> enable-kupomios    # Enable both Ogmios and Kupo

Custom Block Times and Epochs

# Custom slots per epoch
yaci-cli:> create-node -o -e 30 --start
 
# Sub-second block times (e.g., 200ms)
yaci-cli:> create-node -o --block-time 200 --start

Service URLs

When enabled, services are available at:

• Yaci Store (Blockfrost API): http://localhost:8080/api/v1/ (opens in a new tab)
• Yaci Store (Swagger UI): http://localhost:8080/swagger-ui/index.html (opens in a new tab)
• Yaci Viewer: http://localhost:3000 (opens in a new tab) (If Yaci Viewer is installed separately via NPM)
• Ogmios: http://localhost:1337 (opens in a new tab)
• Kupo: http://localhost:1442 (opens in a new tab)

Multi-Node Networks

Since Yaci CLI is used in both Yaci DevKit and this distribution, the commands to create a multi-node network remain the same. You can follow the instructions provided in the Additional Nodes on Different Machines section of the multi-node setup guide.

Next Steps

• Learn all commands: Check out Yaci CLI Commands
• Advanced setup: Set up Multi-node networks
• Testing: Implement Rollback testing
• Compare options: Consider the Docker Setup for easier management