# System Readiness

> Verify hardware and software requirements before deploying a local Hiero test network with Solo. Check system prerequisites, install Docker/Podman, configure platform-specific settings, and ensure your machine is ready.

URL: https://solo.hiero.org/docs/simple-solo-setup/system-readiness/

## Overview

Before you deploy a local Hiero test network with `solo one-shot single deploy`, your machine must meet specific hardware, operating system, and tooling requirements.

This page covers the minimum and recommended memory, CPU, and storage; supported platforms (macOS, Linux, and Windows — natively with PowerShell, or via WSL2); and the required versions of Docker/Podman, Node.js, and Kubernetes tooling.

By the end of this page, your container runtime will be installed and your platform environment configured. Then proceed to [Quickstart](https://solo.hiero.org/docs/simple-solo-setup/quickstart) to install Solo and deploy.

## Hardware Requirements

Solo's resource requirements depend on your deployment size:

| Configuration | Minimum RAM | Recommended RAM | Minimum CPU | Minimum Storage |
| --- | --- | --- | --- | --- |
| Single-node | 12 GB | 16 GB | 4 cores | 20 GB free |
| Multi-node (3+ nodes) | 16 GB | 24 GB | 8 cores | 20 GB free |

> **Note:** If you are using Docker Desktop, ensure the resource limits under
> **Settings → Resources** are set to at least these values - Docker caps usage
> independently of your machine's total available memory.

## Software Requirements

Solo sets up most of the tools it needs for you. The table below shows what each
install method provides, what Solo provisions automatically, and what you must
install yourself.

| Tool | Required version | How it is installed |
| --- | --- | --- |
| [Solo](https://github.com/hiero-ledger/solo) | latest | `npm install -g @hiero-ledger/solo@latest` (recommended); `brew install hiero-ledger/tools/solo` (deprecated - Homebrew support ends August 31, 2026) |
| [Node.js](https://nodejs.org/en/download) | >= 22.0.0 (lts/jod) | **You install it** (required for npm); Homebrew installs it automatically (deprecated) |
| Container runtime ([Docker](https://www.docker.com/products/docker-desktop) / [Podman](https://podman.io)) | See [Docker](#docker) below | **You install it** — Docker Desktop (macOS/Windows) or Docker Engine (Linux). Solo auto-installs Podman on Linux/macOS/WSL2 if Docker Engine is not found. Not supported on native Windows. |
| [kubectl](https://kubernetes.io/docs/reference/kubectl/) | >= v1.32.2 | **Solo provisions it** at deploy time - reuses a compatible copy already on your system, or downloads one into `~/.solo/bin` |
| [Helm](https://helm.sh) | v3.14.2 | **Solo provisions it** at deploy time |
| [Kind](https://kind.sigs.k8s.io) | >= v0.29.0 | **Solo provisions it** at deploy time |
| [Kubernetes](https://kubernetes.io) | >= v1.32.2 | Installed automatically by Kind |
| [k9s](https://k9scli.io/topics/install/) (optional) | >= v0.27.4 | You install it |

> **Note:** Solo's provisioned copies of kubectl, Kind, and Helm live in `~/.solo/bin`,
> which is not necessarily on your `PATH`. If you want to run `kubectl`, `kind`, or `helm`
> commands yourself (some guides do), install [kubectl](https://kubernetes.io/docs/tasks/tools/),
> [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation), and
> [Helm](https://helm.sh/docs/intro/install/) on your `PATH` separately.

### Windows (WSL2) prerequisite

Kind (which Solo provisions automatically) requires WSL2 to be enabled on
Windows, but you do not need a WSL2 Linux distro installed — only the WSL2
feature itself. Enable it with:

```powershell
wsl --install --no-distribution
```

WSL2 requires hardware virtualization and the Virtual Machine Platform Windows
feature. If virtualization is unavailable (for example, `wsl --install` reports
`HCS_E_HYPERV_NOT_INSTALLED`), use the native **Windows (PowerShell)** path
instead, which does not require WSL2.

## Docker

Solo requires Docker Desktop (macOS, Windows) or Docker Engine / Podman (Linux) with sufficient resources:

- **Memory**: at least 12 GB available for containers.
- **CPU**: at least 6 cores available for containers.

### Configure Resources by Platform

#### macOS and Windows (Docker Desktop)

To allocate the required resources in Docker Desktop:

1. Open **Docker Desktop**.
2. Go to **Settings > Resources > Memory** and set it to at least **12 GB**.
3. Go to **Settings > Resources > CPU** and set it to at least **6 cores**.
4. Click **Apply & Restart**.

   ![Docker Desktop resource allocation settings](https://solo.hiero.org/docs/simple-solo-setup/docker_resource_image.png)

> **Note:** If Docker Desktop does not have enough memory or CPU allocated, the one-shot deployment will fail or produce unhealthy pods.

#### Linux

Docker Engine on Linux uses system memory directly and does not have a resource allocation interface like Docker Desktop.

**Resource Check:**
- Ensure your machine has **at least 12 GB of free RAM** available before running `solo one-shot single deploy`.
- Check available memory with: `free -h`
- If you have insufficient RAM, the deployment may fail or pods may become unhealthy.

**Podman on Linux:**
If using Podman instead of Docker Engine, ensure your system has at least 12 GB of free RAM available.

## Platform Setup

Solo supports **macOS**, **Linux**, and **Windows** (natively with PowerShell, or via WSL2). Select your platform below to install the required container runtime and configure your environment, before proceeding to Quickstart:

> ⚠️ **Homebrew support is being deprecated.** Solo will stop publishing updates to Homebrew after August 31, 2026. New users should install via npm. Existing Homebrew users should migrate before August 31.

**macOS**

1. Install Node.js (>= 22.0.0):

    Download from [nodejs.org](https://nodejs.org/en/download), or install via [nvm](https://github.com/nvm-sh/nvm#installing-and-updating):

    ```sh
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
    source ~/.nvm/nvm.sh
    nvm install --lts
    ```

2. Install Docker Desktop:
    - Download from: [https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)
    - Start Docker Desktop and configure resources:
      - **Settings → Resources → Memory**: set to at least **12 GB**
      - **Settings → Resources → CPU**: set to at least **6 cores**
      - Click **Apply & Restart**

    > **macOS prerequisite:** Docker Desktop must be open before running `solo one-shot single deploy`. The Docker daemon is not started automatically on macOS, so confirm Docker Desktop is running from your menu bar before you begin.

3. Install Solo:

    ```sh
    npm install -g @hiero-ledger/solo@latest
    ```

4. Verify the installation:

    ```sh
    solo --version
    ```

**Linux**

1. Install Node.js (>= 22.0.0):

    Using [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) (recommended):

    ```sh
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
    source ~/.nvm/nvm.sh
    nvm install --lts
    ```

    Or download from [nodejs.org](https://nodejs.org/en/download).

2. Install Docker Engine (Ubuntu/Debian):

    ```sh
    sudo apt-get update
    sudo apt-get install -y docker.io
    sudo systemctl enable docker
    sudo systemctl start docker
    sudo usermod -aG docker ${USER}
    ```

    Log out and back in for the group changes to take effect.

    > **Fedora/RHEL:** Replace the `apt-get` commands above with your distro's
    > package manager. For example, on Fedora: `sudo dnf install -y docker-ce
    > docker-ce-cli containerd.io` (after adding Docker's dnf repo — see
    > [Docker's Fedora guide](https://docs.docker.com/engine/install/fedora/)).
    > Then run `sudo systemctl enable --now docker` and
    > `sudo usermod -aG docker ${USER}`.

3. Install Solo:

    ```sh
    npm install -g @hiero-ledger/solo@latest
    ```

4. Verify the installation:

    ```sh
    solo --version
    ```

**Windows**

Run Solo natively from **Windows PowerShell**. Run every command below in a PowerShell terminal.

1. Install Docker Desktop for Windows:
    - Download from: [https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop).
    - Start Docker Desktop and configure resources:
      - **Settings → Resources → Memory**: set to at least **12 GB**
      - **Settings → Resources → CPU**: set to at least **6 cores**
      - Click **Apply & Restart**

    > **Windows prerequisite:** Docker Desktop must be running before you run `solo one-shot single deploy`.

2. Install Node.js (>= 22.0.0):

    ```powershell
    winget install OpenJS.NodeJS.LTS
    ```

    Or download the installer from [nodejs.org](https://nodejs.org/en/download).

> **Note:** Open a new PowerShell window after installing tools so updated PATH entries take effect.

Your environment is ready. Proceed to [Quickstart](https://solo.hiero.org/docs/simple-solo-setup/quickstart) to install Solo and deploy.

**Windows (WSL2)**

> **Note:** Make sure your machine meets the
> [Windows (WSL2) prerequisite](#windows-wsl2-prerequisite) first. If WSL
> and a Linux distribution are already installed, skip step 1 (and you may use a
> distribution other than Ubuntu).

1. Run the following command in Windows PowerShell (as Administrator), then reboot and open the Ubuntu terminal. All subsequent commands must be run inside the Ubuntu (WSL2) terminal.

   ```sh
   wsl --install Ubuntu
   ```

2. Install Node.js (>= 22.0.0) inside the Ubuntu terminal:

    Using [nvm](https://github.com/nvm-sh/nvm#installing-and-updating):

    ```sh
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
    source ~/.nvm/nvm.sh
    nvm install --lts
    ```

3. Install Docker Desktop for Windows:
    - Download from: [https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)
    - Enable WSL2 integration: **Settings → Resources → WSL Integration**
    - Configure resources:
      - **Settings → Resources → Memory**: set to at least **12 GB**
      - **Settings → Resources → CPU**: set to at least **6 cores**
      - Click **Apply & Restart**

4. Install Solo:

    ```sh
    npm install -g @hiero-ledger/solo@latest
    ```

5. Verify the installation:

    ```sh
    solo --version
    ```

## Optional Tools

The following tools are not required but are recommended for monitoring and managing your local network:

- **k9s** (`>= v0.27.4`): A terminal-based UI for managing Kubernetes clusters. Install it with:

  ```bash
  brew install k9s
  ```

  Run `k9s` to launch the cluster viewer.

## Version Compatibility Reference

| Solo Version | Node.js             | Consensus Node | Kubernetes | Docker Resources               | Release Date | End of Support |
|--------------|---------------------|----------------|------------|--------------------------------|--------------|----------------|
| 0.98.0 (LTS) | >= 22.0.0 (lts/jod) | v0.78.1        | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-11-17   | 2027-02-17     |
| 0.97.0       | >= 22.0.0 (lts/jod) | v0.78.1        | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-11-10   | 2026-12-10     |
| 0.96.0 (LTS) | >= 22.0.0 (lts/jod) | v0.78.1        | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-11-04   | 2027-02-04     |
| 0.95.0       | >= 22.0.0 (lts/jod) | v0.78.1        | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-10-27   | 2026-11-27     |
| 0.94.0 (LTS) | >= 22.0.0 (lts/jod) | v0.77.2        | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-10-20   | 2027-01-20     |
| 0.92.0 (LTS) | >= 22.0.0 (lts/jod) | v0.77.2        | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-10-06   | 2027-01-06     |
| 0.90.0 (LTS) | >= 22.0.0 (lts/jod) | v0.76.4        | >= v1.32.2 | Memory >= 12GB, CPU cores >= 6 | 2026-09-22   | 2026-12-22     |

To see a list of legacy releases, please check the [legacy versions documentation page](https://github.com/hiero-ledger/solo/blob/main/legacy-versions.md).

## Troubleshooting Installation

If you experience issues installing or upgrading Solo - for example, conflicts
with a previous installation - clean up your environment and reinstall:

- To **remove a legacy npm install** or perform a **full environment reset**
  (delete Solo-managed Kind clusters and your `~/.solo` directory), see the
  [Cleanup guide](https://solo.hiero.org/docs/simple-solo-setup/cleanup).
- To **upgrade an existing install**, install a **specific version**, or switch
  between Homebrew and npm, see
  [Upgrading an existing Solo installation](https://solo.hiero.org/docs/simple-solo-setup/upgrading-solo).
- **macOS "mounts denied" error on Apple Silicon**: If `solo one-shot single deploy`
  fails immediately with a **"mounts denied"** or **"path is not shared from the host"**
  error, add `/opt/homebrew` to Docker Desktop's File Sharing list:
  **Settings → Resources → File Sharing → +** → add `/opt/homebrew` → **Apply & Restart**.
  This can occur on Apple Silicon Macs (M1/M2/M3/M4) when Homebrew's install path
  (`/opt/homebrew`) is not included in Docker Desktop's shared directories.
  Intel Mac users (Homebrew path `/usr/local`) are not affected.
- **WSL2 fails to install** (for example, `wsl --install` reports
  `HCS_E_HYPERV_NOT_INSTALLED`): WSL2 requires hardware virtualization and the
  Virtual Machine Platform feature. See Microsoft's
  [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install) guide, or
  use the native **Windows (PowerShell)** path, which does not require WSL2.
- **First deploy fails with a PostgreSQL startup timeout**: If
  `solo one-shot single deploy` fails during mirror node setup with a
  PostgreSQL startup timeout, this is a known intermittent issue on first
  deploy. Destroy the deployment and retry:

  ```sh
  solo one-shot single destroy
  solo one-shot single deploy
  ```
