Platform-Specific Setup Instructions

Platform-Specific Setup Instructions

Table of Contents

• macOS Setup
• Linux Setup
• Windows Setup

macOS Setup

System Requirements

• macOS 10.15 (Catalina) or later
• At least 8GB RAM
• Command Line Tools or Xcode

Initial Setup

1. Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation, add Homebrew to PATH:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

2. Install Command Line Tools

xcode-select --install

Common Development Tools

Git

brew install git
git --version

Configure Git:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Python

# Install Python 3.11
brew install python@3.11

# Verify installation
python3 --version
pip3 --version

Node.js (via nvm)

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

# Load nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Install Node.js LTS
nvm install --lts
nvm use --lts

Docker Desktop

1. Download from https://www.docker.com/products/docker-desktop
2. Install the .dmg file
3. Start Docker Desktop from Applications
4. Verify: docker --version

VS Code

brew install --cask visual-studio-code

Shell Configuration

macOS uses zsh by default. Configure your ~/.zshrc:

# Add to ~/.zshrc

# Homebrew
eval "$(/opt/homebrew/bin/brew shellenv)"

# nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Python
export PATH="/opt/homebrew/opt/python@3.11/bin:$PATH"

# Aliases
alias python=python3
alias pip=pip3

Linux Setup

Ubuntu/Debian-based Systems

System Update

sudo apt-get update
sudo apt-get upgrade -y

Essential Build Tools

sudo apt-get install -y build-essential curl git wget

Common Development Tools

Git

sudo apt-get install -y git

# Configure
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Python

# Install Python 3.11
sudo apt-get install -y python3.11 python3.11-venv python3-pip

# Create symlinks (optional)
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.11 1
sudo update-alternatives --install /usr/bin/pip pip /usr/bin/pip3 1

Node.js (via nvm)

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

# Reload shell configuration
source ~/.bashrc

# Install Node.js LTS
nvm install --lts
nvm use --lts
nvm alias default node

Docker

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

# Add Docker's 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

# Add 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

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

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

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

VS Code

# Download and install
wget -O code.deb 'https://code.visualstudio.com/sha/download?build=stable&os=linux-deb-x64'
sudo apt install ./code.deb
rm code.deb

Shell Configuration

Configure your ~/.bashrc:

# Add to ~/.bashrc

# nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Aliases
alias ll='ls -alF'
alias la='ls -A'
alias l='ls -CF'

Windows Setup

Windows Subsystem for Linux (WSL) - Recommended

1. Enable WSL

Open PowerShell as Administrator:

wsl --install

This installs WSL 2 and Ubuntu by default.

2. Set Up Ubuntu on WSL

After reboot, Ubuntu will launch automatically. Create a user account.

Update the system:

sudo apt-get update
sudo apt-get upgrade -y

3. Install Windows Terminal (Optional but Recommended)

Install from Microsoft Store: https://aka.ms/terminal

Development Tools in WSL

Follow the Linux Setup instructions above within your WSL Ubuntu environment.

Native Windows Tools

Git for Windows

1. Download from https://git-scm.com/download/win
2. Install with default options
3. Configure:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Python

1. Download from https://www.python.org/downloads/
2. Important: Check "Add Python to PATH" during installation
3. Verify in Command Prompt:

python --version
pip --version

Node.js

1. Download from https://nodejs.org/
2. Install LTS version
3. Verify in Command Prompt:

node --version
npm --version

Docker Desktop for Windows

1. Download from https://www.docker.com/products/docker-desktop
2. Install and enable WSL 2 backend
3. Start Docker Desktop
4. Verify: docker --version

VS Code

1. Download from https://code.visualstudio.com/
2. Install with default options
3. Install "Remote - WSL" extension for WSL integration

PowerShell Configuration

Configure your PowerShell profile ($PROFILE):

# Create profile if it doesn't exist
if (!(Test-Path -Path $PROFILE)) {
    New-Item -ItemType File -Path $PROFILE -Force
}

# Edit profile
notepad $PROFILE

Add to profile:

# Aliases
Set-Alias -Name ll -Value Get-ChildItem
Set-Alias -Name python3 -Value python
Set-Alias -Name pip3 -Value pip

# Functions
function which($name) {
    Get-Command $name | Select-Object -ExpandProperty Definition
}

Git Bash (Alternative to WSL)

Git for Windows includes Git Bash, a Unix-like terminal:

1. Install Git for Windows
2. Launch Git Bash
3. Follow similar commands as Linux setup
4. Configuration file: ~/.bashrc

Cross-Platform Considerations

Environment Variables

macOS/Linux (~/.bashrc or ~/.zshrc):

export API_KEY="your-key-here"
export DATABASE_URL="postgresql://localhost/mydb"

Windows (PowerShell $PROFILE):

$env:API_KEY = "your-key-here"
$env:DATABASE_URL = "postgresql://localhost/mydb"

Windows (System Environment Variables):

• Right-click "This PC" → Properties
• Advanced system settings → Environment Variables
• Add/edit user or system variables

Path Separators

• Unix-like: / (forward slash)
• Windows: \ (backslash) or / (forward slash often works)

Line Endings

Configure Git to handle line endings:

macOS/Linux:

git config --global core.autocrlf input

Windows:

git config --global core.autocrlf true

File Permissions

Unix-like systems use file permissions (chmod). Windows uses different permission model:

macOS/Linux:

chmod +x script.sh

Windows: Right-click → Properties → Security

Verification Checklist

After setup, verify your environment:

All Platforms

# Git
git --version

# Python
python --version  # or python3 --version
pip --version     # or pip3 --version

# Node.js
node --version
npm --version

# Docker
docker --version
docker ps

# Editor
code --version  # VS Code

Create Test Project

# Create directory
mkdir test-project
cd test-project

# Initialize Git
git init

# Create Python virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows

# Initialize Node.js project
npm init -y

# Verify Docker
docker run hello-world

If all commands work successfully, your environment is ready! 🎉