Machine Setup
Install Docker, Git, and essential development tools for the Zer0-Mistakes Jekyll theme. Cross-platform setup for macOS, Windows, and Linux.
Table of Contents
Machine Setup
Install the tools you need before starting Jekyll development. This guide covers macOS, Windows, and Linux.
flowchart LR
A([Start]) --> B[Install Docker Desktop]
B --> C[Install Git]
C --> D[Configure Git]
D --> E[Install GitHub CLI]
E --> F[Authenticate gh]
F --> G([Ready for Jekyll Setup])
Prerequisites at a Glance
| Tool | macOS | Windows | Linux | Required? |
|---|---|---|---|---|
| Docker Desktop | brew install --cask docker |
winget install Docker.DockerDesktop |
get.docker.com | Yes |
| Git | brew install git |
winget install Git.Git |
apt install git |
Yes |
| GitHub CLI | brew install gh |
winget install GitHub.cli |
pkg install | Yes |
| VS Code | brew install --cask visual-studio-code |
winget install Microsoft.VisualStudioCode |
snap install code --classic |
Recommended |
Step 1 — Install Docker Desktop
Docker runs your Jekyll site in an isolated container so you never fight Ruby version conflicts.
macOS (Homebrew)
brew install --cask docker
# Then open Docker.app to complete setup
open /Applications/Docker.app
Windows (Winget)
winget install Docker.DockerDesktop
# Restart, then launch Docker Desktop from the Start menu
Linux
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker # apply group without logging out
Verify:
docker --version && docker compose version
Step 2 — Install Git
macOS
brew install git
Windows
winget install Git.Git
Linux
sudo apt install git # Debian/Ubuntu
sudo dnf install git # Fedora/RHEL
Step 3 — Configure Git
Replace the values below with your real GitHub username and the no-reply email from github.com/settings/emails:
git config --global user.name "YourGitHubUsername"
git config --global user.email "ID+username@users.noreply.github.com"
git config --global core.editor "code --wait"
Verify:
git config --global --list
Step 4 — Install GitHub CLI
macOS
brew install gh
Windows
winget install GitHub.cli
Linux
sudo apt install gh # Debian/Ubuntu (after adding the gh apt repo)
# Full instructions: https://cli.github.com/manual/installation
Authenticate:
gh auth login
# Choose: GitHub.com → HTTPS → Login with a web browser
# Copy the one-time code shown, press Enter, paste in the browser
Step 5 — Install VS Code (Recommended)
macOS
brew install --cask visual-studio-code
Windows
winget install Microsoft.VisualStudioCode
Linux
sudo snap install code --classic
Useful extensions for Jekyll work:
code --install-extension redhat.vscode-yaml
code --install-extension yzhang.markdown-all-in-one
code --install-extension sissel.shopify-liquid
code --install-extension ms-vscode-remote.remote-containers
code --install-extension ms-azuretools.vscode-docker
Verify Everything
docker --version && docker compose version
git --version
gh --version
code --version
macOS: Install All Tools with Homebrew
If you’re on macOS and don’t have Homebrew yet, install it first:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Then install everything in one go:
brew install git gh
brew install --cask docker visual-studio-code
Troubleshooting
Docker: permission denied (Linux)
sudo usermod -aG docker $USER && newgrp docker
Docker Desktop won’t start (Windows)
Ensure Hyper-V or WSL 2 is enabled. Run wsl --install in an elevated PowerShell, then restart.
Port 4000 already in use
lsof -i :4000 # find the PID
kill <PID> # free the port