Solana Sample Project & Installation Guide | Rust Project Series

This chapter covers the complete end-to-end installation and bootstrap process for setting up a local Solana development environment using Windows Subsystem for Linux (WSL). We will install all required toolchains—including Node.js, Yarn, Rust, Solana CLI, and Anchor—generate a sample Anchor project, and execute our first successful test run.

1. Why Do We Need a Specialized Solana Installation Guide?

Unlike traditional software development where installing a package manager is straightforward, blockchain infrastructure setups—specifically for Solana, Substrate, and Hyperledger—are notoriously complex and version-sensitive.

• Non-Standard Toolchains: Solana is written in Rust, and its smart contracts (programs) are also written in Rust. However, local development requires orchestrating a JavaScript/TypeScript testing layer alongside the core systems level binaries.
• Fragile Documentation: Official installation guides frequently change or drift, causing installation scripts to break on monthly updates.
• OS Compatibility Strategy: Advanced distributed ledger tooling often fails natively on Windows. Using WSL (Windows Subsystem for Linux) provides a stable, isolated Linux environment inside Windows, allowing developers to spawn specific Ubuntu versions (e.g., Ubuntu 20.04) tailored for blockchain runtimes.

Note: WSL is strongly recommended for Windows users building with Solana, Substrate, or Near Protocol to avoid hard-to-debug compiler mismatches and missing shared libraries (libssl, build-essential).

2. Core Mental Model & Architecture Analogy

To understand the Solana local development stack, we can map its tooling directly to the more familiar Ethereum development ecosystem:

3. High-Level Installation & Project Workflow

The end-to-end bootstrap sequence follows a strict dependency order. Skipping steps or running commands out of order will result in build failures.

4. Step-by-Step Environment Setup

Step 4.1: Install curl and Node Version Manager (NVM)

First, ensure curl is present on your WSL instance, then install NVM to manage Node.js versions safely.

# Verify or install curl
sudo apt update && sudo apt install curl -y
curl --version

# Install NVM (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload shell configuration or restart terminal
source ~/.bashrc
nvm --version

Step 4.2: Install Node.js, Mocha, and Yarn

Anchor relies on Node.js and JavaScript testing frameworks (like Mocha) to orchestrate test suites, much like Hardhat does for Ethereum.

# Install latest LTS Node.js via NVM
nvm install --lts
nvm use --lts
node -v

# Install Mocha (testing framework) and Yarn (package manager globally)
npm install --global mocha
yarn --version

Step 4.3: Verify the Rust Toolchain

Because Solana smart contracts are written in Rust, you must have the Rust compiler and package manager installed and updated.

# Verify rustup, compiler, and cargo versions
rustup --version
rustc --version
cargo --version

Expected minimum output: Rust compiler and Cargo versions 1.64.0 or higher.

5. Installing and Configuring Solana CLI

Step 5.1: Install the Solana Suite

Execute the official Solana installation script provided by the Solana Labs team:

sh -c "$(curl -sSfL https://release.solana.com/v1.14.10/install)"

(Note: Add the returned binary path to your ~/.bashrc or ~/.zshrc PATH variable as instructed by the installer output).

Verify the installation:

solana --version

Step 5.2: Configure Localhost RPC and WebSocket Endpoints

Point your Solana CLI configuration to your local machine rather than public testnets or mainnets:

# Set cluster to local validator
solana config set --url localhost

# Confirm configuration settings
solana config get

Expected Configuration Output:

• RPC URL: http://localhost:8899
• WebSocket URL: ws://localhost:8900/

6. Installing Anchor and the Anchor Version Manager (AVM)

Anchor is a framework for Solana's Sealevel runtime providing convenient developer tools, similar to Hardhat in Ethereum. We use AVM (Anchor Version Manager) to manage Anchor installations.

Step 6.1: Install AVM and Anchor CLI

# Install AVM from cargo
cargo install --git https://github.com/coral-xyz/anchor --tag v0.25.0 avm --locked

# Install the latest Anchor CLI using AVM
avm install latest
avm use latest

# Verify Anchor CLI version
anchor --version

Real-World Pitfall & Debugging (libssl errors): In roughly 50% of fresh WSL Ubuntu installations, cargo install for Anchor will fail because the environment lacks basic cryptographic libraries (libssl-dev) and build essentials. If your cargo build fails, fix it immediately by running:

BASH

Copy

sudo apt-get update && sudo apt-get install -y pkg-config build-essential libssl-dev libudev-dev

7. Creating and Exploring a Sample Anchor Project

Step 7.1: Initialize a New Project

Create a new Anchor project configured to use JavaScript/TypeScript for testing:

anchor init solana-youtube-demo --javascript
cd solana-youtube-demo

Step 7.2: Examine Project Directory Structure

Open the newly created directory in your code editor (e.g., VS Code):

code .

Review the modular project layout:

8. Executing Tests and Running the Local Validator

Understanding Local Validator Behavior

When testing Solana programs locally, you have two options for running the local validator node:

1. Manual Background Node: Running solana-test-validator in a dedicated terminal window.
2. Integrated Test Runner: The anchor test command automatically spins up an ephemeral local validator instance behind the scenes, executes the test suite, and tears it down.

Crucial Rule: Do not manually run solana-test-validator in a separate terminal at the same time you execute anchor test. Doing so will cause a port conflict (Port 8899 is already in use), causing your build to fail.

Running the Test Suite

Execute the test command from your project root:

anchor test

Successful Execution Flow:

If you see 1 passing accompanied by transaction signatures and program hashes, your environment is fully operational.

Summary and Key Takeaways

• WSL Necessity: Windows users must develop Solana applications inside WSL (Ubuntu) to prevent native compiler incompatibilities and missing C-library dependencies.
• Dependency Hierarchy: Tool installation must follow strict order: Node.js/NVM -> Yarn/Mocha -> Rust/Cargo -> Solana CLI -> AVM/Anchor CLI.
• System Dependencies: Fresh WSL builds frequently lack libssl-dev and build-essential, causing Cargo compilation failures that require explicit apt-get installation.
• Ethereum Mappings: Anchor maps to Hardhat, Solana Test Validator maps to Geth, and AVM maps to NVM.
• Localhost Configuration: Always verify your Solana CLI config points to http://localhost:8899 before running local tests.
• Port Conflict Management: anchor test automatically launches its own local validator instance; never run solana-test-validator concurrently in another terminal window to avoid port 8899 collisions.
• Graceful Shutdown: Always stop running blockchain nodes using Ctrl + C rather than Ctrl + Z to ensure listening ports release cleanly without hanging processes.