Machine Setup

By Amr

Estimated reading time: 21 minutes

Edit on GitHub

Machine Setup for Zer0-Mistakes Jekyll Theme

Transform your development environment with Docker-first setup for the Zer0-Mistakes Jekyll theme. This modern approach eliminates dependency conflicts and ensures consistent development across all platforms.

🚀 Quick Start (Recommended)

One-Line Installation with AI-Powered Setup

curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash

This intelligent installation script:

  • ✅ Auto-detects your operating system and architecture
  • ✅ Installs Docker if not present (with user confirmation)
  • ✅ Configures environment with optimal settings
  • ✅ Self-heals common installation issues
  • ✅ Validates setup with comprehensive health checks

🐳 Docker-First Development

Why Docker?

  • 🔄 Consistency: Identical environment across macOS, Windows, and Linux
  • ⚡ Speed: Instant setup without Ruby version management
  • 🛡️ Isolation: No conflicts with system Ruby or other projects
  • 🎯 Simplicity: Single command to start development
  • 📦 Portability: Share exact development environment with team

Docker Installation

macOS:

# Intel Macs
brew install --cask docker

# Apple Silicon Macs (M1/M2/M3)
brew install --cask docker
# Docker Desktop automatically handles ARM64 compatibility

Windows:

# Install Docker Desktop
winget install Docker.DockerDesktop

# Alternative: Use Windows Subsystem for Linux (WSL2)
wsl --install
winget install Docker.DockerDesktop

Linux:

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# CentOS/RHEL/Fedora
sudo dnf install docker docker-compose
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Verify Docker Installation

docker --version
docker-compose --version

# Test Docker functionality
docker run hello-world

🛠️ Development Tools

Essential Tools

1. Git (Version Control)

# macOS
brew install git

# Windows
winget install Git.Git

# Linux (Ubuntu/Debian)
sudo apt install git

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

2. GitHub CLI (Repository Management)

# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

# Authenticate with GitHub
gh auth login

3. Visual Studio Code (Recommended Editor)

# macOS
brew install --cask visual-studio-code

# Windows
winget install Microsoft.VisualStudioCode

# Linux
sudo snap install code --classic

VS Code Extensions for Jekyll Development

Install these essential extensions for optimal Jekyll development:

# Install via Command Line
code --install-extension ms-vscode.vscode-json
code --install-extension redhat.vscode-yaml
code --install-extension yzhang.markdown-all-in-one
code --install-extension ms-vscode-remote.remote-containers
code --install-extension ms-azuretools.vscode-docker
code --install-extension github.vscode-pull-request-github
code --install-extension sissel.shopify-liquid
code --install-extension ginfuru.ginfuru-better-solarized-dark-theme
code --install-extension pkief.material-icon-theme
code --install-extension streetsidesoftware.code-spell-checker

Key Extensions:

  • Remote - Containers: Develop inside Docker containers
  • Docker: Container management and debugging
  • Liquid: Jekyll template language support
  • YAML: Configuration file support
  • Markdown All in One: Enhanced Markdown editing
  • GitHub Pull Requests: Seamless GitHub integration

🔧 Platform-Specific Setup

macOS Configuration

Xcode Command Line Tools (for Git and other development tools):

xcode-select --install

Homebrew Package Manager:

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

Windows Configuration

Windows Subsystem for Linux (WSL2) - Recommended for optimal Docker performance:

# Enable WSL2
wsl --install

# Set WSL2 as default
wsl --set-default-version 2

# Install Ubuntu distribution
wsl --install -d Ubuntu

Windows Terminal (Enhanced terminal experience):

winget install Microsoft.WindowsTerminal

Linux Configuration

Docker Compose (if not included with Docker):

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

✅ Verification & Health Check

After setup completion, verify your environment:

# Check Docker functionality
docker --version
docker-compose --version
docker run hello-world

# Check Git configuration
git --version
git config --list

# Check GitHub CLI
gh --version
gh auth status

# Test VS Code
code --version

🚨 Troubleshooting

Common Issues & Solutions

Docker Permission Issues (Linux):

sudo usermod -aG docker $USER
newgrp docker

Docker Desktop Not Starting (Windows/macOS):

  • Ensure virtualization is enabled in BIOS/UEFI
  • On Windows: Enable Hyper-V or WSL2
  • Restart Docker Desktop application

Port Conflicts:

# Check what's using port 4000
lsof -ti:4000
# Kill process if needed
kill $(lsof -ti:4000)

🎯 Next Steps

With your machine setup complete:

  1. 🔗 GitHub Setup - Configure repositories and authentication
  2. 🏗️ Jekyll Setup - Start your Docker-based Jekyll development
  3. 📖 Quickstart Overview - Complete development workflow guide

💡 Pro Tips

  • Use Docker volumes for persistent data storage
  • Enable BuildKit for faster Docker builds: export DOCKER_BUILDKIT=1
  • Configure resource limits in Docker Desktop for optimal performance
  • Use .dockerignore to exclude unnecessary files from build context
  • Leverage multi-stage builds for smaller production images

This Docker-first approach ensures you’ll have a reliable, consistent development environment that “just works” across all platforms! 🎉

Before you can begin developing, your machine (computer) needs to be configured and loaded with the necessary software and dependencies. Each OS (Windows, Mac, Linux) will have its own method to download and install software based on the technology stack you’re working with. In this guide, we will focus on how to build a Minimal Viable Product (MVP) to prep your machine to create a Static Website Generator using Jekyll.

Core Setup Overview

For this guide, we will be using the following tools:

  • Software Package Manager
    • Retrieves your applications/libraries/code through a trusted repository
      • winget (Windows)
      • Homebrew (Mac)
      • APT (Linux)
  • Source Code Repository
    • The place where your code is stored and managed
  • Integrated Development Environment (IDE)
    • Visual Studio Code
    • The best integrated development environment for beginners to advanced programmers
  • Programming Languages
    • Ruby
      • The programming language and framework used by Jekyll and Github pages
    • Python
      • A programming language used for various tasks
    • JavaScript
      • The programming language used for web development
    • liquid
      • The templating language used by Jekyll

Software Package Manager

A package manager is a software that allows you to install, upgrade, remove other software packages on your computer in a consistent manner. With a package manager, you can easily maintain and track your collection of software packages required for use, but also install any other packages that are dependant in order to function.

The job of a package manager is to present an interface which assists the user in managing the collection of packages installed on his or her system.

MacOS

The most popular package manager for MacOS is Homebrew. Homebrew is a package manager for macOS. It simplifies the installation of software on the Mac operating system. It is a free and open-source software package management system that simplifies the installation of software on Apple’s macOS operating system.

Install docs

  • Homebrew is a package manager for macOS.

For more information, visit the Homebrew website.

# Install Homebrew
bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

confirm that you have installed Homebrew by running the following command:

# Confirm Homebrew installation
brew -v

Windows

the most popular package manager for Windows is Winget. Winget is a package manager for Windows. It is a command-line tool that allows you to install, update, and manage software packages on your Windows machine. Winget is a package manager for Windows that allows you to install, update, and manage software packages from the command line.

for more information, visit the Winget website.

  • Winget - is a package manager for Windows.

Linux

Depending on the distribution of Linux you are using, you will have a different package manager. Some of the most popular package managers for Linux are:

  • APT -Debian/Ubuntu
  • YUM - Fedora
  • RPM - Redhat/CentOS

Source Code Repository

A source code repository is a file archive and web hosting facility where a large amount of source code, for software or for web pages, is kept, either publicly or privately. They are often used by open-source projects and other multi-developer projects to maintain and manage the source code.

  • Git is a distributed version control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files.
  • Github is a web-based platform that uses Git for version control. It is a repository hosting service that provides a web-based graphical interface and access control for repositories. It is commonly used for code. It offers all of the distributed version control and source code management (SCM) functionality of Git as well as adding its own features.
  • Github CLI is a command line interface for the Github API. It is used to create and manage repositories. It is also used to create and manage issues and pull requests.

git installation

to install git on your machine, you can use the following commands:

MacOS

# Install git via Homebrew
brew install git

Windows

# Install git via Winget
winget install git.git

Linux

# Install git via APT
sudo apt install git

Detailed instructions

git configuration

Find your User ID in the github emails settings more info here 

$GIT_ID = Read-Host "What is your Github ID?"
$GIT_USER_NAME = Read-Host "What is your Github User Name?"
git config --global user.name "$GIT_USER_NAME@users.noreply.github.com"
git config --global user.email "$GIT_ID+$GIT_USER_NAME@users.noreply.github.com"

echo 'What is your Github ID?'
read GIT_ID
echo 'What is your Github User Name?'
read GIT_USER_NAME
git config --global user.name "$
git config --global user.email "$

Github Command Line Interface

to install the Github CLI on your machine, you can use the following commands:

MacOS

# Install Github CLI via Homebrew
brew install gh

Windows

# Install Github CLI via Winget
winget install GitHub.cli

Linux

# Install Github CLI via APT
sudo apt install gh

apt install

The Github CLI is a command line interface for the Github API. It is used to create and manage repositories. It is also used to create and manage issues and pull requests.

# Install Github CLI the hard way
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/etc/apt/trusted.gpg.d/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/trusted.gpg.d/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

Confirm that you have installed the Github Command Line Interface by running the following command:

# Confirm Github CLI installation
gh --version

Login to gh cli using your github credentials

# Login to gh cli
gh auth login

Install Software Packages (optional)

Most people are familiar with downloading and installing software from a website the manual way. However, there are a few things that can be done with the package manager that can make it easier and automatic. For instance, you can install a package with a single command (i.e. brew cask install visual-studio-code), or you can install multiple packages at once.

This repository has 2 submodules that contain files for installing different collections of software. You can find the files in the \homebrew or \winget directory.

To add submodules to your repository, run the following command:

git submodule add https://github.com/bamr87/homebrew.git submodules/homebrew
git submodule add https://github.com/bamr87/winget-packages submodules/winget

If the directories are empty, run the following command to fetch the submodules:

git submodule update --init

to pull the latest changes from the submodule, run the following command:

git submodule update --remote

Mac

Detailed instructions for installing software packages can be found in the Brewfile section.

# Navigate to your home directory and clone the brewfile
cd ~
gh repo clone bamr87/brewfile ~/.brew

# Navigate into brew file repo and install packages
cd ~/.brew
brew bundle
brew bundle --file bundles/core/

Or install individually using a loop

# Include init_world/hello-mac/hb-packages.sh
mkdir _quest/init_world/hello-mac/
ln ../_quest/init_world/hello-mac/hb-packages.sh _quest/init_world/hello-mac/hb-packages.sh

Linux

# Navigate to your home directory and clone the brewfile
cd ~
gh repo clone bamr87/apt ~/.apt

# Navigate into brew file repo and install packages
cd ~/.apt
apt bundle
apt bundle --file bundles/core/

windows

For a list of packages you can download/install using winget, see here

For a list of package bundles, see here

Detailed instructions for installing software packages can be found in the Winget section.

# Navigate to your home directory and clone the winget packages
cd ~
gh repo clone bamr87/winget-packages .winget

# Navigate into winget file repo and install packages
cd ~/.winget
winget import --import-file winget-app-core.json
winget import --import-file winget-app-dev.json

Here’s a recommended list of VS Code extensions to install:

aaron-bond.better-comments
DavidAnson.vscode-markdownlint
eliostruyf.vscode-front-matter
esbenp.prettier-vscode
Gruntfuggly.todo-tree
James-Yu.latex-workshop
leodevbro.blockman
mdickin.markdown-shortcuts
ms-azuretools.vscode-docker
ms-dotnettools.csharp
ms-kubernetes-tools.vscode-kubernetes-tools
ms-python.python
ms-python.vscode-pylance
ms-toolsai.jupyter
ms-toolsai.jupyter-keymap
ms-toolsai.jupyter-renderers
ms-vscode-remote.remote-containers
ms-vscode-remote.remote-wsl
ms-vscode.powershell
ms-vsliveshare.vsliveshare
ms-vsliveshare.vsliveshare-audio
ms-vsliveshare.vsliveshare-pack
redhat.vscode-xml
redhat.vscode-yaml
sissel.shopify-liquid
streetsidesoftware.code-spell-checker
syler.sass-indented
TakumiI.markdowntable
tchayen.markdown-links
telesoho.vscode-markdown-paste-image
yzhang.markdown-all-in-one

source

Iterating over file to install extensions

cd ~/github/it-journey/_quickstart
Get-Content extensions.txt | ForEach-Object {code --install-extension $_}

Install VS Code

VS Code is a text editor that integrates well with Github. It is a free and open source software editor.

Mac

#install VS Code via Homebrew
brew cask install visual-studio-code

Detailed instructions - Mac

windows

#install VS Code via Winget
winget install Microsoft.VisualStudioCode

Detailed instructions - Windows

Linux

Detailed instructions - Linux

#install VS Code via APT
sudo apt install code

#install VS Code via Homebrew
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/trusted.gpg.d/
sudo sh -c 'echo "deb [arch=amd64,arm64,armhf signed-by=/etc/apt/trusted.gpg.d/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
rm -f packages.microsoft.gpg

Then update the package cache and install the package using:

sudo apt install apt-transport-https
sudo apt update
sudo apt install code # or code-insiders

Log into VS code using your github account by clicking on the Account icon on the bottom left of the VS code window.

Install Ruby

Ruby is the programming language of choice for Jekyll, and also manages the dependencies for the Jekyll gem.

Mac

# Install Ruby
brew install ruby@2.7

windows

# Install Ruby (version 2.7 for github pages)
winget install RubyInstallerTeam.RubyWithDevKit.2.7 -v 2.7.4-1

If this doesn’t work, download the MSI file and install manually.

Ruby Downloads

Linux

# Install Ruby via APT
sudo apt-get install ruby-full build-essential zlib1g-dev

# Add Ruby to your PATH if you're using Zsh
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Add Ruby to PATH (Mac and Linux)

Ah, the $PATH variable in Linux and MacOS – it’s like the wise old map of a seasoned explorer! This variable is crucial because it tells your system where to look for the executable files (those little adventurers that actually run your commands) when you type a command in the terminal.

Imagine you’re in a vast library (your computer) looking for a specific book (a program, like python or git). Now, if this library had no organization, you’d be wandering around forever! That’s where $PATH comes in – it’s like a magical index telling you exactly in which aisles (directories) to look for your book (executable file).

When you type a command, the system checks each directory listed in your $PATH variable, in the order they’re listed. If it finds the executable file in one of these directories, voilà! The command runs. If not, it’s like hitting a dead end in a maze, and you get an error saying the command wasn’t found.

You can see your current $PATH by typing echo $PATH in the terminal. It shows a list of paths, separated by colons. You can add new paths to it, ensuring that your system knows about more places to look for your programs.

Just remember, with great power comes great responsibility. Modify the $PATH wisely, or you might lead your system into a labyrinth of confusion!

After install, you need to add the executables to your PATH. Otherwise, you will not be able to run Ruby or Jekyll.

First check which terminal shell you are using:

echo $SHELL

Add new PATH to ruby 2.7 by inserting into your profile

# This tells your system where to look for the executable files and where the gems are located

export PATH="/usr/local/opt/ruby/bin:/usr/local/opt/ruby@2.7/bin:/usr/local/lib/ruby/gems/2.7.0/bin:$PATH"
export PATH=/usr/local/opt/ruby@2.7/bin:$PATH
export PATH=`gem environment gemdir`/bin:$PATH

# Add Ruby to your PATH if you're using Zsh
echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/2.7.4/bin:$PATH"' >> ~/.zshrc
echo 'export PATH=`gem environment gemdir`/bin:$PATH' >> ~/.zshrc

# Add Ruby to your PATH If you're using Bash
echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/2.7.4/bin:$PATH"' >> ~/.bash_profile

After install, you need to add the executables to your PATH. Otherwise, you will not be able to run Ruby or Jekyll.

First check which terminal shell you are using:

echo $SHELL

# Add Ruby to your PATH if you're using Zsh
echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.zshrc

# Add Ruby to your PATH If you're using Bash
echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.bash_profile

Install Jekyll

Once Ruby is installed, you can install Jekyll. First exit the terminal and open a new terminal to initialize the new PATH variable.

# Install Jekyll and Bundler
gem install --user-install bundler jekyll

Append the Jekyll Gem your path file

First get the ruby version using:

# Get Ruby version
ruby -v

Replace X.X.0 with the version of ruby you just installed

# Add path to zshrc profile
echo 'export PATH="$HOME/.gem/ruby/3.3.0/bin:$PATH"' >> ~/.zshrc

# Add to your .bash_profile
echo 'export PATH="$HOME/.gem/ruby/3.0.0/bin:$PATH"' >> ~/.bash_profile

Restart your terminal

Verify that Jekyll is installed

# Verify Jekyll is installed
jekyll --version

Fork Github Repository

Now you can fork the repository from Github and start working on it.

# Navigate to your home directory, create a github folder, and fork the github repo
cd ~
mkdir github
cd github
gh repo fork bamr87/it-journey

If you want to clone the repository to your local machine, you can run the following command:

# Clone the repository to your local machine
gh repo clone bamr87/it-journey

Install Dependencies

Once the repo is installed, you can install the dependencies for the Jekyll gem.

# Navigate to your github repo and install dependencies
cd ~/github/it-journey
bundle install

Build Jekyll site

To build the Jekyll site, you need to run the following command:

# Build Jekyll site
jekyll build

Start Site locally

To start the site locally, you need to run the following command:

# Start Jekyll site locally
jekyll serve

Install Xcode Command Line Tools

Homebrew requires Xcode Command Line Tools to be installed if Xcode is not already installed.

Open the Terminal (Command + Space) and run the following command:

xcode-select --install

Confirm that you have installed Xcode Command Line Tools by running the following command:

xcode-select -p

Set SDKROOT (only macOS Catalina or later)

export SDKROOT=$(xcrun --show-sdk-path)

Windows Developer Settings (Windows 10 only)

Update your OS settings to allow shell scripts to execute and to install winget (if applicable). Without this setting, you may run into issues later on.

dev settings

NOTE: This change opens up a lot of security vualnerabilities so proceed with caution.

Install Winget (Windows 10 only)

Winget is a package manager for Windows and is developed and maintained here.

Downloadable msi files can be found here.

Install docs

You can directly download the msi file from the following link:

Winget install

Or you can run the following commands in Powershell to download the msi file:

# Navigate to the directory where the msi file will be installed
cd ~
$download_folder = ".winget"
mkdir $download_folder
cd $download_folder

# Download installation package

$version = "v1.1.12653"
$url = "https://github.com/microsoft/winget-cli/releases/download/$version/Microsoft.DesktopAppInstaller_8wekyb3d8bbwe.msixbundle"
$FileName = Split-Path $url -Leaf
$FullPath = "$pwd\$FileName"

$webclient = New-Object System.Net.WebClient
$webclient.DownloadFile($url, $FullPath)

echo "Saved $FileName"

Open installation file

ii $FullPath

Silent Install Option

msiexec /i $FullPath /qn /norestart

Iterm2

brew install iterm2

$ sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Windows Terminal

Oh-My-Posh

OMP

Nerd Fonts

Nerd fonts git repo

Windows Sub Linux

install docs

Download Ubuntu

Invoke-WebRequest -Uri https://aka.ms/wslubuntu2004 -OutFile Ubuntu.appx -UseBasicParsing
wsl --set-default-version 2

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Docker

Windows Instructions wsl

Docker Instructions