HomepageStake NowLog in ->

Solana Localnet

Solana has three public clusters: Mainnet, Testnet and Devnet. All of these require coordination with other parties in one way or another, and it becomes hard for devs to reset state when developing locally.

The Hayek Validator Toolkit includes a fourth cluster named Localnet, which runs 100% inside a Docker container, and spins up a fully functioning Solana network with multiple coordinating validators in seconds.

Benefits

Exploration: The main benefit of the Solana Localnet is that it promotes exploration without fear. It is a disposable environment that is easy to setup, take down, change, and break as much as you want.

Speed: Launching the Solana Localnet in your workstation takes seconds. Coordinating between nodes is instant.

State: Resetting state of a validator node, spining a new validator that can join Localnet, or turning off validators is near instant. Even better, you can completely delete the docker localnet cluster, and spin it again if you feel you corrupted the state doing something.

Automation: One of the nodes of Localnet is an Ansible Control node, which will let you run ansible scripts against your Localnet nodes as well as Mainnet and Testnet.

Workstation Setup

Before running the Hayek Validator Kit Solana Localnet, you must setup your workstation for success.

All the configurations related to the Hayek Validator Kit are in this GitHub repo, which you will have to clone locally if you have not done so already:

git clone https://github.com/team-supersafe/hayek-validator-kit.git

You should get familiar with the contents of the repo. The Localnet cluster is defined in the Dockerfile and docker-compose.yml files under the solana-localnet folder.

The Localnet Cluster

Pre-Provisioned Demo Key Set

We have pre-provisioned a sets of keys called demo1 only for demonstration and debugging purposes.

Name
Address
Explorer links

validator identity

demoneTKvfN3Bx2jhZoAHhNbJAzt2rom61xyqMe5Fcw

solana explorer, solscan

vote account

demo52s9s1foFXgnbVa8vYQM8GS9XRsJ3aMpus1rNnb

solana explorer, solscan

user stake account

demoMwLKQwfPZpjrbGG7Ed6vbXizxFDCp5srVd1Hqky

solana explorer, solscan

The demo1 identity key will be running with 200k SOL staked in Localnet every time you start the cluster. These 200k SOL represents roughly ~16% of all cluster stake.

Host Inventory

The Localnet cluster consist of the following containers:

Container Node
Key Features

gossip-entrypoint - SSH port binding: localhost:9022

The cluster's Gossip protocol entry point node. Any validator can use this to join the network and synchronize with other validators.

  • It provides Genesis block for Solana Localnet

  • Kick-starts POH

  • Epoch = 750 slots (~5 min)

  • Mostly for cluster boilerplate and not meant to be modified

host-alpha

- SSH port binding: localhost:9122

Running the demo1 validator key set with:

  • 200K delegated SOL (~16% of all cluster stake)

host-bravo - SSH port binding: localhost:9222

A validator-ready container without a validator key set. It does not have any validator running, but the tooling is already installed.

host-charlie - SSH port binding: localhost:9322

A naked Ubuntu 24.04. This guy is not ready for anything. This is good to test bare-bone provisioning scripts.

ansible-control - Not SSH bound

- See how to connect

Your official sysadmin automation environment:

  • Solana CLI and Ansible installed

  • Access Solana Mainnet, Testnet and Localnet

  • Connect to any Localnet container via SSH.

After the cluster is provisioned, the staked SOL delegated to the demo1 key set will be active at the beginning of Epoch 1 (after ~5 minutes). Then the demo1 validator will start voting and move from delinquent to not-delinquent at the beginning of Epoch 2.

Using Explorers

You can use the Solana Explorer and Solscan apps to explore any accounts in your localnet cluster using these addresses:

Running Localnet on Unix-based OS

We use Docker to run Localnet:

  1. IDE Option (recommended) Open the repo in VSCode or another popular IDE and select "Reopen in Container" or similar option. This will use the Dev Containers extension to automatically run the services containers defined in docker-compose.yml and trigger the build process of the images in the Dockerfile if needed.

  2. Terminal Option Another option, for those VSCode haters, is the run Localnet directly from the terminal by running:

Congratulations! You are now running Solana Localnet, connected to your Ansible Control and ready to make a mess of your Localnet playground.

Running Localnet on Windows

There are some things that are unique to running Localnet on Windows (as opposed to MacOS or Linux).

  1. Install VS Code for Windows: https://code.visualstudio.com/download

  2. Install WSL: https://learn.microsoft.com/es-es/windows/wsl/install

  3. Open the “wsl distro" from the start menu (Ubuntu by default) and create your Linux username and password. Note that these credentials are independent of your Windows account.

  4. Install ANSIBLE in the WSL environment:

    1. Run the following command to update the system repository information:

    2. Install the prerequisite packages that allow you to add the official Ansible PPA:

    3. Add the PPA with the following command and install the package:

  5. Install the package dos2unix:

Dos2unix is a command-line utility used to convert text files from DOS/MAC format, which uses carriage return and line feed (CRLF) for line endings, to Unix format, which uses only line feed (LF). This conversion helps ensure compatibility when transferring files between different operating systems.

  1. Go to the solana-localnet folder, the path should look like this:

Run the following command:

  1. In VS Code, create a .env file for the environment variables. Paste the following variables, taking care to replace YOUR_WINDOWS_USERNAME placeholder with the proper one:

Remember to create and save your workspace in Visual Studio Code.

  1. Install the following programs on the Windows host:

    1. Docker desktop for windows: https://docs.docker.com/desktop/setup/install/windows-install/

    2. Python: https://www.python.org/downloads/windows/

  2. In VS Code use the option “reopen from container”.

  3. Check that the containers are running on Docker Desktop:

Resetting Localnet

At times, and as you corrupt the state of your docker containers running in Localnet, you may need to reset your docker Localnet cluster to start fresh. You can accomplish this by selecting the options of "Reopen in Container" or "Rebuild Container" within VSCode.

You can also stop the cluster from docker with:

SSH into nodes

From Workstation

Ports are mapped from your localhost to each container:

  • localhost:9022 → gossip-entrypoint:22

  • localhost:9122 → host-alpha:22

  • localhost:9222 → host-bravo:22

  • localhost:9322 → host-charlie:22

From Ansible Control

Using the Solana CLI in localnet

We will use the solana gossip and solana validators command to illustrate how to correctly configure the RPC url depending on from where we are running the commands.

Directly from our workstation

From ansible-control

From a validator node

After the first login into one of the validator hosts (host-alpha and host-bravo), we set the RPC_URL environment variable pointing to the gossip-entrypoint host, so we can use that variable when using the Solana CLI, like so:

Other common validator CLI commands can be found HERE.

Cluster Example

Entrypoint Node

An entrypoint container can use this command to run:

... and it will output the following:

If --gossip-host <IP_ADDRESS> is not provided here, any agave-validator client trying to connect through gossip will try hard for a while...

... and eventually die with this message:

Validator Nodes

Troubleshooting

If your validator doesn't show up as a running process or the process is running but it never catches up of falls behind, make sure to check the logs before anything else:

References

Reference credits for the Dockerfile for ubuntu-ansible:

PreviousGitHub RepoNextAnsible Control

Last updated

Was this helpful?