Module 1: Preparation

Learning objectives

By the end of this module, you will have:

✅ Verified your system meets the requirements
✅ Installed WSL2 (Windows users)
✅ Installed Docker Desktop
✅ Installed VS Code (code editor)
✅ Installed Git
✅ Prepared your workspace

Estimated time: 20-50 minutes, depending on your system and internet speed.

Before you begin

This module prepares your computer for EvoNEST installation. We'll install the necessary software and verify that your system is ready.

Important

You'll need administrator privileges on your computer to install software. Make sure you have these before proceeding.

Step 1: Check system requirements

Minimum requirements

Before installing EvoNEST, verify your system meets these requirements:

Operating System
- Windows 10/11 (64-bit) or
- macOS 10.X or newer or
- Linux (Ubuntu, Fedora, Debian)
Hardware
- 4GB RAM minimum (16GB recommended)
- 20GB free disk space
- Dual-core processor (quad-core recommended)
Permissions
- Administrator/sudo privileges
- Ability to install software
Internet Connection
- Required for downloading Docker and the repository

How to check your system specs

Windows:

Press Windows Key + Pause/Break or search for "About Your PC"
Check "Installed RAM" and "System type"

macOS:

Click Apple menu → "About This Mac"
Check Memory and Storage tabs

Linux:

bash

# Check RAM
free -h

# Check disk space
df -h

# Check OS version
lsb_release -a

Step 2: Install WSL2 (Windows only)

What is WSL2?

WSL2 (Windows Subsystem for Linux 2) allows Windows to run a Linux environment. Docker Desktop on Windows requires WSL2 to work properly.

If you're on macOS or Linux, skip to Step 3.

Check if WSL2 is already installed

Before installing, let's check if you already have WSL2:

Open PowerShell
- Press Windows Key
- Type "PowerShell"
- Click "Windows PowerShell" (no need for administrator mode yet)
Check WSL version
Run this command:
bash
```
wsl --status
```
If you see version information and "Default Version: 2":
- ✅ WSL2 is already installed! Skip to Step 3
If you see an error or "command not found":
- Continue with installation below

Install WSL2

For detailed installation instructions, please follow Microsoft's official guide:

Install WSL2 on Windows

The Microsoft guide will walk you through:

Installing WSL2 with a single command
Setting up your Linux distribution
Troubleshooting common issues

Quick summary

For most users, the installation is simple:

Open PowerShell as Administrator
Run: wsl --install
Restart your computer
Complete the Ubuntu setup when prompted

See the Microsoft guide for detailed steps and troubleshooting.

Verify WSL2 installation

After following the Microsoft guide and restarting, verify your installation:

Open PowerShell and run:

bash

wsl --status

Expected output:

Default Distribution: Ubuntu
Default Version: 2

✅ If you see "Default Version: 2", WSL2 is ready!

Step 3: Install Docker Desktop

Docker is the platform that runs EvoNEST. We'll install Docker Desktop, which includes everything you need.

For Windows

Download Docker Desktop
- Visit: https://www.docker.com/products/docker-desktop/
- Click "Download for Windows"
Run the Installer
- Double-click Docker Desktop Installer.exe
- Follow the installation wizard
- Important: When prompted, enable "Use WSL 2 instead of Hyper-V" (recommended)
- Since you installed WSL2 in Step 2, this should work smoothly
Restart Your Computer
- Docker will prompt you to restart
- Restart is required to complete installation
Start Docker Desktop
- After restart, launch Docker Desktop from the Start menu
- Accept the service agreement
- Skip the tutorial (we'll guide you through everything)

Troubleshooting Windows installation

"WSL 2 installation is incomplete" error:

This shouldn't happen if you completed Step 2
Verify WSL2 is installed: Open PowerShell and run wsl --status
If needed, return to Step 2 and complete WSL2 installation

Docker Desktop won't start:

Make sure WSL2 is running: Open PowerShell and run wsl --status
Restart Docker Desktop
Check if virtualization is enabled in your BIOS (consult your PC manufacturer's documentation)

For macOS

Check your Mac's processor
- Click Apple menu → "About This Mac"
- Note whether you have "Intel" or "Apple Silicon" (M1/M2/M3)
Download Docker Desktop
- Visit: https://www.docker.com/products/docker-desktop/
- Click "Download for Mac"
- Choose the correct version:
  - Mac with Intel chip → Intel Chip version
  - Mac with Apple Silicon → Apple Silicon version
Install Docker Desktop
- Open the downloaded .dmg file
- Drag Docker icon to Applications folder
- Open Docker from Applications
Grant permissions
- Docker will ask for permissions
- Enter your password when prompted
- Accept the service agreement

Troubleshooting macOS installation

"Docker Desktop requires macOS 10.15 or later":

You need to update macOS first
Go to System Preferences → Software Update

"System Extension Blocked":

Go to System Preferences → Security & Privacy
Click "Allow" for Docker system extension
Restart Docker Desktop

For Linux

Ubuntu/DebianFedora

bash

# Update package index
sudo apt-get update

# Install dependencies
sudo apt-get install ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to docker group (avoid needing sudo)
sudo usermod -aG docker $USER

# Log out and back in for group changes to take effect

bash

# Install DNF plugins
sudo dnf -y install dnf-plugins-core

# Add Docker repository
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

# Install Docker Engine
sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group
sudo usermod -aG docker $USER

After installation, log out and log back in for group changes to take effect.

Step 4: Verify Docker installation

Let's make sure Docker is working correctly.

Open a terminal/command prompt
- Windows: Search for "Command Prompt" or "PowerShell"
- macOS: Open "Terminal" from Applications → Utilities
- Linux: Open your terminal application
Check Docker version
Run this command:
bash
```
docker --version
```
Expected output:
```
Docker version 24.0.0, build abc1234
```
✅ If you see a version number, Docker is installed correctly!

Test Docker is running

Run this command:

bash

docker run hello-world

Expected output:

Hello from Docker!
This message shows that your installation appears to be working correctly.
[... more text ...]

✅ If you see this message, Docker is working!

Docker not running?

If you see "Cannot connect to Docker daemon":

Make sure Docker Desktop is running
- Look for the Docker icon in your system tray/menu bar
- If it's not there, launch Docker Desktop
Wait for Docker to fully start
- Docker can take 1-2 minutes to start on first launch
- Watch for the icon to stop animating
Try the test command again

Linux users: If group permissions don't work

If you're still getting permission errors after logging out and back in, try restarting your computer instead of just logging out and back in
You can use sudo before docker commands:

bash

sudo docker run hello-world

Step 5: Install a code editor (VS Code)

We recommend installing Visual Studio Code (VS Code) as your code editor for working with EvoNEST.

Why VS Code?

VS Code is a free, lightweight code editor with excellent support for JavaScript, TypeScript, and React. It has built-in Git integration and many helpful extensions for web development.

Check if VS Code is already installed

Try running:

bash

code --version

✅ If you see a version number, VS Code is already installed! Skip to Step 6.

Installing VS Code

WindowsmacOSLinux

bash

# Download VS Code from:
# https://code.visualstudio.com/

# Run the installer with default settings
# After installation, restart your terminal and verify:
code --version

bash

# Download VS Code from:
# https://code.visualstudio.com/

# Open the downloaded .zip file
# Drag "Visual Studio Code" to Applications folder
# Verify installation:
code --version

bash

# Ubuntu/Debian - Download .deb package from:
# https://code.visualstudio.com/
# Then install:
sudo apt install ./code_*.deb

# Or use snap:
sudo snap install --classic code

# Fedora - Download .rpm package from:
# https://code.visualstudio.com/
# Then install:
sudo dnf install ./code-*.rpm

# Verify installation
code --version

Step 6: Install Git

Git is used to download (clone) the EvoNEST code repository.

Check if Git is already installed

Open your terminal and run:

bash

git --version

✅ If you see a version number (e.g., git version 2.40.0), Git is already installed! Skip to Step 7.

Installing Git

If you don't have Git installed:

WindowsmacOSLinux

bash

# Download Git for Windows from:
# https://git-scm.com/download/win

# Run the installer with default settings
# After installation, restart your terminal and verify:
git --version

bash

# Option 1: Install via Homebrew (if you have it)
brew install git

# Option 2: Install Xcode Command Line Tools
xcode-select --install

# Verify installation
git --version

bash

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install git

# Fedora
sudo dnf install git

# Verify installation
git --version

Step 7: Create a workspace folder

Let's create a dedicated folder for your EvoNEST installation.

Choose a location for your EvoNEST files
- This is not the same folder where your data or the applications are going to be stored, as we are using Docker. We advise to create a folder in your common work directory, e.g. Documents/Work/EvoNEST
Create the folder:

Windows (Command Prompt)Windows (PowerShell)macOS/Linux

bash

# Navigate to your Documents folder
cd %USERPROFILE%\Documents\Work

# Create EvoNEST folder
mkdir EvoNEST

# Enter the folder
cd EvoNEST

bash

# Navigate to your Documents folder
cd ~/Documents

# Create EvoNEST folder
mkdir EvoNEST

# Enter the folder
cd EvoNEST

bash

# Navigate to your Documents folder
cd ~/Documents

# Create EvoNEST folder
mkdir EvoNEST

# Enter the folder
cd EvoNEST

Verify you're in the right place:
bash
```
pwd
```
You should see something like:
- Windows: C:\Users\YourName\Documents\EvoNEST
- macOS: /Users/YourName/Documents/EvoNEST
- Linux: /home/YourName/Documents/EvoNEST

Keep this terminal open

Keep your terminal window open - you'll use it in the next module for installation!

Checkpoint: are you ready?

Before moving to the next module, verify you have:

Windows users only: WSL2 installed (wsl --status **Windows users only:** WSL2 installed (`wsl --status` shows "Default Version: 2")
Docker Desktop installed and running
Docker tested successfully (docker run hello-world Docker tested successfully (`docker run hello-world` worked)
VS Code installed (code --version VS Code installed (`code --version` shows a version number)
Git installed (git --version Git installed (`git --version` shows a version number)
Created a workspace folder (e.g., Documents/EvoNEST Created a workspace folder (e.g., `Documents/EvoNEST`)
Terminal/command prompt open in your workspace folder

All set?

If you've checked all the boxes above, you're ready to proceed!

Need help?

If something didn't work, check the Troubleshooting guide for assistance.

Next steps

Congratulations! Your system is now prepared for EvoNEST installation.

In the next module, you'll:

Clone the EvoNEST repository
Configure your environment
Start EvoNEST for the first time

Module 1: Preparation ​

Before you begin ​

Step 1: Check system requirements ​

Minimum requirements ​

Step 2: Install WSL2 (Windows only) ​

Check if WSL2 is already installed ​

Install WSL2 ​

Verify WSL2 installation ​

Step 3: Install Docker Desktop ​

For Windows ​

For macOS ​

For Linux ​

Step 4: Verify Docker installation ​

Step 5: Install a code editor (VS Code) ​

Check if VS Code is already installed ​

Installing VS Code ​

Step 6: Install Git ​

Check if Git is already installed ​

Installing Git ​

Step 7: Create a workspace folder ​

Checkpoint: are you ready? ​

Next steps ​

Module 1: Preparation

Before you begin

Step 1: Check system requirements

Minimum requirements

Step 2: Install WSL2 (Windows only)

Check if WSL2 is already installed

Install WSL2

Verify WSL2 installation

Step 3: Install Docker Desktop

For Windows

For macOS

For Linux

Step 4: Verify Docker installation

Step 5: Install a code editor (VS Code)

Check if VS Code is already installed

Installing VS Code

Step 6: Install Git

Check if Git is already installed

Installing Git

Step 7: Create a workspace folder

Checkpoint: are you ready?

Next steps