Development Environment Setup - Hands-on Walkthrough

In this module, you'll set up the essential development tools needed for vibecoding: Node.js (with npm and nvm) and Docker (with Docker Compose). These tools form the foundation for building and running modern applications, containers, and MCP servers.

Prerequisites

See module overview for full prerequisites list.

What We'll Install

Node.js Ecosystem:

Node.js (~100 MB) - JavaScript runtime for running scripts and servers
npm (included with Node.js) - Node package manager for installing dependencies
npx (included with Node.js) - Tool for running npm packages without installation
nvm - Node Version Manager for switching between Node.js versions

Docker Ecosystem:

Docker Engine/Desktop (~500 MB - 1 GB) - Container platform for running isolated applications
Docker Compose (included in Docker Desktop, separate on Linux) - Tool for defining multi-container applications

Why these tools?

Node.js powers MCP servers, web applications, and automation scripts
Docker enables consistent environments across different machines
nvm allows working on projects requiring different Node.js versions
Docker Compose simplifies running complex multi-service applications

Time required: 15-20 minutes

Part 1: Node.js Installation

What We'll Do

Install Node.js, which includes npm and npx. We'll install the LTS (Long Term Support) version for stability.

Choose your operating system and follow the instructions:

Windows

Step 1: Download Node.js Installer

Open browser and navigate to: https://nodejs.org/
Click the LTS button (left button, typically shows version like 20.x.x)
Download completes: node-v20.x.x-x64.msi (~30 MB)

Step 2: Run Installer

Double-click the downloaded .msi file
Click Next through the installation wizard
Important: Keep "Add to PATH" checkbox checked (default)
Accept license agreement
Keep default installation location: C:\Program Files\nodejs\
Click Install (requires administrator privileges)
Wait for installation to complete (~1-2 minutes)
Click Finish

Step 3: Verify Installation

Open PowerShell or Command Prompt and run:

node --version
npm --version
npx --version

Expected output:

v20.11.0
10.2.4
10.2.4

Your version numbers may be slightly different - that's okay!

macOS

Step 1: Download Node.js Installer

Open browser and navigate to: https://nodejs.org/
Click the LTS button (shows version like 20.x.x)
Download completes: node-v20.x.x.pkg (~30 MB)

Step 2: Run Installer

Open the downloaded .pkg file
Click Continue through the installation wizard
Accept license agreement
Keep default installation location
Click Install (will prompt for your password)
Enter your macOS password
Wait for installation to complete (~1-2 minutes)
Click Close

Step 3: Verify Installation

Open Terminal and run:

node --version
npm --version
npx --version

Expected output:

v20.11.0
10.2.4
10.2.4

Linux

Step 1: Update Package Index

Open terminal and update your package list:

sudo apt update

Step 2: Install Node.js via NodeSource Repository

NodeSource provides up-to-date Node.js packages for Debian/Ubuntu.

# Download and run NodeSource setup script for Node.js 20.x LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js and npm
sudo apt install -y nodejs

For other Linux distributions:

Fedora/RHEL/CentOS: See https://github.com/nodesource/distributions#rpm
Arch Linux: sudo pacman -S nodejs npm
openSUSE: sudo zypper install nodejs npm

Step 3: Verify Installation

node --version
npm --version
npx --version

Expected output:

v20.11.0
10.2.4
10.2.4

Part 2: nvm (Node Version Manager)

What We'll Do

Install nvm to manage multiple Node.js versions. This is especially useful when working on different projects that require different Node.js versions.

Note for Windows users: We'll use nvm-windows, which is a separate project from the macOS/Linux nvm.

Choose your operating system:

Windows

Step 1: Download nvm-windows

Navigate to: https://github.com/coreybutler/nvm-windows/releases
Download nvm-setup.exe from the latest release (~2 MB)

Step 2: Run Installer

Double-click nvm-setup.exe
Click Next through the wizard
Accept license agreement
Keep default installation path: C:\Users\[YourName]\AppData\Roaming\nvm
Select Node.js symlink directory: C:\Program Files\nodejs
Click Install
Click Finish

Step 3: Verify nvm Installation

Close and reopen PowerShell (important!), then run:

nvm version

Expected output:

1.1.12

Step 4: List Installed Node.js Versions

nvm list

You should see your currently installed Node.js version.

macOS

Step 1: Install nvm via Homebrew or curl

Option A - Using Homebrew (recommended if you have it):

brew install nvm

Option B - Using curl:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Step 2: Configure Shell Profile

Add nvm to your shell profile. The installer usually does this automatically, but verify:

For bash (default on older macOS):

echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bash_profile
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bash_profile
source ~/.bash_profile

For zsh (default on newer macOS):

echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

Step 3: Verify nvm Installation

nvm --version

Expected output:

0.39.7

Step 4: List Installed Node.js Versions

nvm list

Linux

Step 1: Install nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Step 2: Load nvm

The installer adds nvm to your shell profile automatically. Reload your profile:

# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

Step 3: Verify nvm Installation

nvm --version

Expected output:

0.39.7

Step 4: List Installed Node.js Versions

nvm list

Part 3: Docker Installation

What We'll Do

Install Docker, the container platform that allows running applications in isolated environments. Windows and macOS use Docker Desktop (graphical application), while Linux uses Docker Engine (command-line).

Choose your operating system:

Windows

Step 1: Check Windows Requirements

Docker Desktop for Windows requires:

Windows 10/11 64-bit (Pro, Enterprise, or Education)
WSL 2 (Windows Subsystem for Linux 2) enabled
Virtualization enabled in BIOS

Step 2: Enable WSL 2

Open PowerShell as Administrator and run:

wsl --install

If already enabled, you'll see:

Windows Subsystem for Linux is already installed.

If not enabled:

Installation will proceed (~5 minutes)
Restart your computer when prompted
After restart, continue to Step 3

Step 3: Download Docker Desktop

Navigate to: https://www.docker.com/products/docker-desktop/
Click Download for Windows
Download completes: Docker Desktop Installer.exe (~500 MB)

Step 4: Install Docker Desktop

Double-click Docker Desktop Installer.exe
Keep "Use WSL 2 instead of Hyper-V" checked (recommended)
Keep "Add shortcut to desktop" checked
Click OK to start installation (~5 minutes)
Click Close when installation completes
Restart your computer

Step 5: Start Docker Desktop

Double-click Docker Desktop icon on desktop
Accept service agreement if prompted
Wait for Docker to start (~30 seconds)
Look for whale icon in system tray (bottom-right)
When whale icon is steady (not animated), Docker is running

Step 6: Verify Docker Installation

Open PowerShell and run:

docker --version
docker compose version

Expected output:

Docker version 24.0.7, build afdd53b
Docker Compose version v2.23.3

Note: Docker Desktop includes Docker Compose automatically!

macOS

Step 1: Check macOS Requirements

Docker Desktop for macOS requires:

macOS 11 (Big Sur) or newer
At least 4 GB RAM

Step 2: Download Docker Desktop

Navigate to: https://www.docker.com/products/docker-desktop/
Choose your chip:
- Apple Silicon (M1/M2/M3): Click "Download for Mac - Apple Chip"
- Intel chip: Click "Download for Mac - Intel Chip"
Download completes: Docker.dmg (~500 MB)

Not sure which chip? Click Apple menu → About This Mac:

If you see "Apple M1" or "Apple M2" → Apple Silicon
If you see "Intel Core" → Intel chip

Step 3: Install Docker Desktop

Open Docker.dmg file
Drag Docker icon to Applications folder
Open Applications folder
Double-click Docker app
macOS may ask "Are you sure you want to open it?" → Click Open
Click OK when prompted for privileged access
Enter your macOS password
Accept service agreement if prompted
Wait for Docker to start (~30 seconds)
Look for whale icon in menu bar (top-right)

Step 4: Verify Docker Installation

Open Terminal and run:

docker --version
docker compose version

Expected output:

Docker version 24.0.7, build afdd53b
Docker Compose version v2.23.3

Note: Docker Desktop includes Docker Compose automatically!

Linux

Step 1: Remove Old Docker Versions (if any)

sudo apt remove docker docker-engine docker.io containerd runc

Step 2: Install Prerequisites

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

Step 3: Add Docker's Official GPG Key

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Step 4: Set Up Docker 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

Step 5: Install Docker Engine

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Installation takes ~2-3 minutes.

Step 6: Start Docker Service

sudo systemctl start docker
sudo systemctl enable docker

Step 7: Add Your User to Docker Group (optional but recommended)

This allows running Docker without sudo:

sudo usermod -aG docker $USER

Log out and log back in for this change to take effect.

Step 8: Verify Docker Installation

docker --version
docker compose version

Expected output:

Docker version 24.0.7, build afdd53b
Docker Compose version v2.23.3

For other Linux distributions:

Fedora: https://docs.docker.com/engine/install/fedora/
CentOS: https://docs.docker.com/engine/install/centos/
Arch Linux: sudo pacman -S docker docker-compose

Part 4: Docker Compose

What We Already Have

Good news! Docker Compose installation status varies by platform:

Windows

Docker Compose is already installed!

Docker Desktop for Windows includes Docker Compose v2 by default. You verified this in Part 3, Step 6 when you ran:

docker compose version

No additional steps needed. Skip to Part 5.

macOS

Docker Compose is already installed!

Docker Desktop for macOS includes Docker Compose v2 by default. You verified this in Part 3, Step 4 when you ran:

docker compose version

No additional steps needed. Skip to Part 5.

Linux

Docker Compose is already installed!

When you installed Docker Engine in Part 3, you included the docker-compose-plugin package. You verified this in Part 3, Step 8.

If you need to verify again:

docker compose version

Expected output:

Docker Compose version v2.23.3

Note: Modern Docker uses docker compose (with space), not the older docker-compose (with hyphen).

No additional steps needed. Continue to Part 5.

Part 5: Quick Verification Tests

What We'll Do

Run simple tests to verify everything works correctly. These tests are identical regardless of your operating system.

Test 1: Docker Hello World

Step 1: Run Hello World Container

Open terminal and run:

docker run hello-world

What happens:

Docker downloads the hello-world image (~2 KB)
Creates and runs a container from that image
Container prints a message and exits

Expected output:

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
...
Status: Downloaded newer image for hello-world:latest

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

If you see "Hello from Docker!" → Docker works! ✅

Step 2: Check Docker Images

docker images

You should see the hello-world image listed:

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
hello-world   latest    9c7a54a9a43c   3 months ago   13.3kB

Test 2: Docker Compose with Simple Service

Step 1: Create Test Directory

Navigate to your workspace:

# Windows
cd c:/workspace/hello-genai/work/

# macOS/Linux
cd ~/workspace/hello-genai/work/

Create test directory:

mkdir 110-task
cd 110-task

Step 2: Create docker-compose.yml File

Create a file named docker-compose.yml with this content:

version: '3.8'

services:
  nginx:
    image: nginx:latest
    ports:
      - "8080:80"

How to create the file:

Open your code editor (VS Code or Cursor)
Create new file: docker-compose.yml
Paste the content above
Save in work/110-task/ directory

What this does:

Defines one service named nginx
Uses official nginx web server image
Maps port 8080 on your machine to port 80 in container

Step 3: Start the Service

In terminal, run:

docker compose up -d

Expected output:

[+] Running 2/2
 ✔ Network 110-task_default     Created
 ✔ Container 110-task-nginx-1   Started

What happened:

Docker Compose created a network
Downloaded nginx image (~150 MB) if not present
Started nginx container in background (-d = detached mode)

Step 4: Verify Service is Running

Check running containers:

docker compose ps

Expected output:

NAME                 IMAGE          COMMAND                  STATUS         PORTS
110-task-nginx-1     nginx:latest   "/docker-entrypoint.…"   Up 5 seconds   0.0.0.0:8080->80/tcp

Step 5: Test the Web Server

Open browser and navigate to: http://localhost:8080

You should see: "Welcome to nginx!" page

If you see the nginx welcome page → Docker Compose works! ✅

Step 6: Stop the Service

docker compose down

Expected output:

[+] Running 2/2
 ✔ Container 110-task-nginx-1   Removed
 ✔ Network 110-task_default     Removed

What happened:

Stopped the nginx container
Removed the container
Removed the network

Test 3: Node.js Script Execution

Step 1: Create Simple Node.js Test File

In the same work/110-task/ directory, create test.js:

// Simple Node.js test script
console.log('Node.js is working!');
console.log('Node version:', process.version);
console.log('Platform:', process.platform);

// Simple calculation
const add = (a, b) => a + b;
console.log('2 + 2 =', add(2, 2));

Step 2: Run the Script

node test.js

Expected output:

Node.js is working!
Node version: v20.11.0
Platform: win32
2 + 2 = 4

If you see output with your Node version → Node.js works! ✅

Test 4: npm Package Installation Test

Step 1: Initialize npm Project

Still in work/110-task/ directory:

npm init -y

Expected output:

Wrote to .../work/110-task/package.json

What happened:

Created package.json file
This file tracks project dependencies

Step 2: Install a Simple Package

Install chalk package (adds colors to terminal output):

npm install chalk

Expected output:

added 1 package, and audited 2 packages in 2s
found 0 vulnerabilities

What happened:

Downloaded chalk package from npm registry
Created node_modules/ folder with dependencies
Updated package.json with chalk dependency

Step 3: Test the Installed Package

Create test-npm.js:

import chalk from 'chalk';

console.log(chalk.green('✅ npm is working!'));
console.log(chalk.blue('Package installation successful!'));

Update package.json to add "type": "module":

{
  "name": "110-task",
  "version": "1.0.0",
  "type": "module",
  ...
}

Run the script:

node test-npm.js

Expected output: Green text: ✅ npm is working! Blue text: Package installation successful!

If you see colored output → npm works! ✅

Test 5: npx Quick Test

What is npx? npx runs npm packages without installing them globally. Very useful for one-time commands.

Run a simple npx command:

npx cowsay "Development environment ready!"

First run will prompt:

Need to install the following packages:
  cowsay@1.6.0
Ok to proceed? (y)

Type y and press Enter.

Expected output:

 _________________________________
< Development environment ready! >
 ---------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

If you see the cow → npx works! ✅

Success Criteria

You've successfully completed this module when you can check off:

✅ Node.js installed and verified on your operating system
✅ npm and npx available and working
✅ nvm installed for Node.js version management
✅ Docker installed and running
✅ Docker Compose available and tested
✅ Successfully ran docker run hello-world
✅ Successfully started and stopped nginx with Docker Compose
✅ Successfully ran Node.js script from terminal
✅ Successfully installed and used npm package
✅ Successfully used npx to run package without installation

Understanding Check

Answer these questions to verify comprehension:

What is the difference between Node.js, npm, and npx?

Expected answer: Node.js is the JavaScript runtime that executes JavaScript code outside browsers. npm is the package manager for installing and managing JavaScript packages/dependencies. npx is a tool for running npm packages without installing them globally, useful for one-time commands or testing packages.
Why would you use nvm (Node Version Manager)?

Expected answer: nvm allows you to install and switch between multiple Node.js versions on the same machine. This is crucial when working on different projects that require different Node.js versions, or when testing your code against multiple Node versions.
What's the difference between Docker Desktop (Windows/macOS) and Docker Engine (Linux)?

Expected answer: Docker Desktop is a graphical application that includes Docker Engine, GUI for management, and additional tools like Kubernetes. Docker Engine (Linux) is the core Docker daemon and CLI, installed as a system service. Both run containers the same way, but Desktop provides easier management through UI.
What does docker compose up -d do?

Expected answer: It starts services defined in docker-compose.yml file in detached mode. The -d flag means containers run in the background, allowing you to continue using the terminal. Without -d, container logs would be displayed in the terminal and it would block.
When would you use Docker vs running applications directly on your machine?

Expected answer: Use Docker when you need consistent environments across machines, isolation between applications, easy deployment, or when application has complex dependencies. Docker ensures "it works on my machine" applies everywhere. Run directly when it's a simple script, you're actively developing and need fast iteration, or overhead isn't worth the isolation.
What's the purpose of package.json in Node.js projects?

Expected answer: package.json is the manifest file for Node.js projects that tracks project metadata, dependencies (packages your project needs), scripts (commands you can run), and version information. It allows others to install exact same dependencies with npm install and ensures reproducible builds.
What command would you use to check if Docker is running?

Expected answer: docker --version checks if Docker is installed. docker ps or docker info checks if Docker daemon is running and shows running containers or system information. On Windows/macOS, you can also check if Docker Desktop app is running via system tray icon.

Troubleshooting

Problem: "node is not recognized" after installation (Windows)

Symptoms: Running node --version shows "command not found" or "not recognized"

Solutions:

Close and reopen terminal - PATH changes require new terminal session
Verify PATH variable:
- Open System Properties → Environment Variables
- Check if C:\Program Files\nodejs\ is in PATH
- If missing, add it manually
Restart computer if PATH changes don't take effect
Reinstall Node.js and ensure "Add to PATH" is checked during installation

Problem: Docker Desktop won't start (Windows)

Symptoms: Docker Desktop shows "Docker Desktop starting..." forever, or fails to start

Solutions:

Enable virtualization in BIOS:
- Restart computer and enter BIOS (usually F2, F10, or Del during boot)
- Find "Virtualization Technology" or "Intel VT-x" / "AMD-V"
- Enable it and save

Enable WSL 2:

wsl --install
wsl --set-default-version 2

Update WSL:
```
wsl --update
```
Check Windows version: Docker Desktop requires Windows 10 build 19041+ or Windows 11
Run as administrator: Right-click Docker Desktop → Run as administrator

Problem: "permission denied" when running docker commands (Linux)

Symptoms: Docker commands fail with "permission denied while trying to connect to Docker daemon"

Solutions:

Add user to docker group:
```
sudo usermod -aG docker $USER
```
Log out and log back in - group changes require new session
Verify group membership:
```
groups
```
You should see docker in the list
Restart Docker service:
```
sudo systemctl restart docker
```
Temporary solution: Prefix commands with sudo:
```
sudo docker ps
```

Problem: nvm commands not found after installation

Symptoms: Running nvm --version shows "command not found"

Solutions:

Windows:

Close and reopen PowerShell
Run PowerShell as administrator
Check if nvm is in PATH
Reinstall nvm-windows

macOS/Linux:

Reload shell profile:

# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

Verify nvm is in profile:
```
cat ~/.bashrc | grep NVM_DIR
```
Should show nvm configuration lines

Manually add to profile if missing:

echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bashrc
source ~/.bashrc

Problem: Port 8080 already in use during Docker Compose test

Symptoms: docker compose up fails with "port is already allocated"

Solutions:

Find what's using the port:

# Windows
netstat -ano | findstr :8080

# macOS/Linux
lsof -i :8080

Stop the process using the port or choose different port

Edit docker-compose.yml to use different port:

ports:
  - "8081:80"  # Use 8081 instead of 8080

Stop all Docker containers:
```
docker stop $(docker ps -aq)
```

Problem: npm install fails with network errors

Symptoms: Package installation fails with "ETIMEDOUT", "ENOTFOUND", or network errors

Solutions:

Check internet connection
Clear npm cache:
```
npm cache clean --force
```

Try different registry:

npm config set registry https://registry.npmjs.org/

Use VPN if behind firewall/proxy
Check if npm registry is accessible:
```
curl https://registry.npmjs.org/
```

Problem: Docker Desktop requires Windows update

Symptoms: Installation fails with "Windows version not supported"

Solutions:

Check Windows version:
- Press Win + R
- Type winver and press Enter
- Note the build number
Update Windows:
- Settings → Update & Security → Windows Update
- Install all available updates
- Restart computer
Required minimum: Windows 10 build 19041 or Windows 11
If can't update: Consider using Docker Toolbox (older solution) or Linux VM

Next Steps

Congratulations! You have a complete Node.js and Docker development environment ready. Here's what comes next:

Practice with containers

Experiment with Docker:
- Try different images from Docker Hub (postgres, redis, mongodb)
- Create multi-service applications with Docker Compose
- Learn Docker basics: images, containers, volumes, networks
Explore Node.js ecosystem

Build JavaScript skills:
- Create simple Node.js scripts
- Install and use popular npm packages
- Use nvm to switch between Node versions for different projects
Prepare for MCP development

Your environment is now ready for:
- Module 100: Understanding Model Context Protocol
- Building MCP servers with Node.js
- Running MCP servers in Docker containers
- Integrating with AI assistants
Continue to Module 120: Rapid POC Prototyping

Learn how to quickly prototype ideas using your new development environment.

Additional Resources

Ready to continue your training? Head to Module 120: Rapid POC Prototyping

FilesExpand file tree

walkthrough.md

Latest commit

History

walkthrough.md

File metadata and controls

Development Environment Setup - Hands-on Walkthrough

Prerequisites

What We'll Install

Part 1: Node.js Installation

What We'll Do

Windows

macOS

Linux

Part 2: nvm (Node Version Manager)

What We'll Do

Windows

macOS

Linux

Part 3: Docker Installation

What We'll Do

Windows

macOS

Linux

Part 4: Docker Compose

What We Already Have

Windows

macOS

Linux

Part 5: Quick Verification Tests

What We'll Do

Test 1: Docker Hello World

Test 2: Docker Compose with Simple Service

Test 3: Node.js Script Execution

Test 4: npm Package Installation Test

Test 5: npx Quick Test

Success Criteria

Understanding Check

Troubleshooting

Problem: "node is not recognized" after installation (Windows)

Problem: Docker Desktop won't start (Windows)

Problem: "permission denied" when running docker commands (Linux)

Problem: nvm commands not found after installation

Problem: Port 8080 already in use during Docker Compose test

Problem: npm install fails with network errors

Problem: Docker Desktop requires Windows update

Next Steps

Additional Resources