Workstation Setup¶

Quick Overview

What: Install the essential workstation tools for building and managing your homelab. Why: These tools are your toolbox—Git, Docker, Terraform, and more. Time: 30–90 minutes depending on installs. XP: Up to 70 points (like Whose Line, the points are made up but the fun is real).

Entry Checks¶

macOS or Windows with admin rights
Git and GitHub account
Docker Desktop available

Outcomes¶

Install and configure Git and GitHub CLI
Install Wrangler and validate Cloudflare login
Install Docker Desktop and verify installation
Install Terraform and validate setup
(Optional) Install Ansible and validate setup on supported platforms

With your hardware ready, it’s time to prepare your workstation. These tools are the core kit that will let you manage, automate, and interact with every part of your homelab journey.

Preparing Package Managers¶

macOSWindows

Install Homebrew (macOS package manager) (if not already installed):

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

Install Chocolatey (Windows package manager) (if not already installed):

Set-ExecutionPolicy Bypass -Scope Process -Force; `
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; `
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Install curl (if not already available):
```
choco install curl
```
Validate:
```
curl --version
```

Labs¶

2.1 Git and GitHub CLI¶

Git and GitHub CLI

Git is a distributed version control system. GitHub CLI brings GitHub actions to your terminal. These are essential for managing infrastructure code and collaborating on the homelab.

Create a GitHub account at github.com if you don't already have one.

macOSWindows

Install Git and GitHub CLI:
```
brew install git gh
```
Authenticate GitHub CLI:
```
gh auth login
```

Install Git and GitHub CLI:
```
choco install git gh
```
Authenticate GitHub CLI:
```
gh auth login
```

Validation¶

Run git --version to verify Git is installed.
Run gh auth status to confirm GitHub CLI is authenticated.

🏆 Achievement Unlocked: GitHub connected!

2.2 Cloudflare Wrangler¶

Cloudflare Wrangler

Wrangler is the CLI (Command Line Interface) tool for managing Cloudflare services, including Workers and DNS.

macOSWindows

Install Node.js (if not already installed):
```
brew install node
```
Install Wrangler via npm:
```
npm install -g wrangler
```
Authenticate Wrangler:
```
wrangler login
```

Install Node.js (if not already installed):
```
choco install nodejs
```
Install Wrangler via npm:
```
npm install -g wrangler
```
Authenticate Wrangler:
```
wrangler login
```

Validation¶

Run wrangler --version to verify installation.
Run wrangler whoami to confirm authentication.

🏆 Achievement Unlocked: Cloudflare wrangler ready!

2.3 Docker Desktop¶

Docker Desktop

Docker runs applications in containers. Docker Desktop provides the local engine and UX (User Experience) we will use to run services during the labs.

macOSWindows

Install via Homebrew Cask:
```
brew install --cask docker
```
Validate:
```
docker version
docker run hello-world
```

Note: Do not install the separate docker formula. Docker Desktop includes the CLI.

Install Docker Desktop. Enable Kubernetes only if needed later.
```
choco install docker-desktop
```

Note: Do not install the separate docker package. Docker Desktop includes the CLI.

Validate:
```
docker version
docker run hello-world
```

Validation¶

Run docker version to check Docker installation.
Run docker run hello-world to verify container runtime.

🏆 Achievement Unlocked: Docker containerized!

2.4 Terraform Install and Validation¶

Terraform

Terraform defines infrastructure as code (IaC) and provisions cloud or on‑prem resources declaratively.

macOSWindows

Install Terraform:

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

Validate:
```
terraform -version
```

Install Terraform:
```
choco install terraform
```
Validate:
```
terraform -version
```

Validation¶

Run terraform -version to confirm installation.

🏆 Achievement Unlocked: Terraform deployed!

2.5 Vault and Consul CLI¶

HashiCorp Vault and Consul

Vault manages secrets and protects sensitive data. Consul provides service discovery and key‑value storage. Both CLIs (Command Line Interfaces) are needed for later chapters.

macOSWindows

Install Vault and Consul:

brew tap hashicorp/tap
brew install hashicorp/tap/vault hashicorp/tap/consul

Validate:
```
vault --version
consul --version
```

Install Vault and Consul:
```
choco install vault consul
```
Validate:
```
vault --version
consul --version
```

Validation¶

Run vault --version to verify Vault CLI.
Run consul --version to verify Consul CLI.

🏆 Achievement Unlocked: Secrets and service mesh mastered!

2.6 Ansible Install and Validation (optional for Windows)¶

Ansible

Ansible automates configuration management and orchestration for your homelab.

macOSWindows

Install Ansible:
```
brew install ansible
```
Validate:
```
ansible --version
```

Optional on Windows

On Windows, install Ansible via WSL (Windows Subsystem for Linux) or another supported method. Skip if not needed now.

Validate (if installed):
```
ansible --version
```

Validation¶

Run ansible --version to verify installation (if installed).

🏆 Achievement Unlocked: Automation activated!

2.7 Visual Studio Code¶

Visual Studio Code (VS Code)

Visual Studio Code (VS Code) is a flexible editor with rich extensions useful for this lab.

Download

macOSWindows

Install Visual Studio Code via Homebrew Cask:
```
brew install --cask visual-studio-code
```

Install recommended extensions:

hashicorp.terraform
redhat.ansible
ms-azuretools.vscode-docker
redhat.vscode-yaml
github.vscode-github-actions
ms-vscode-remote.remote-containers
gruntfuggly.todo-tree
esbenp.prettier-vscode
yzhang.markdown-all-in-one

code --install-extension hashicorp.terraform
code --install-extension redhat.ansible
code --install-extension ms-azuretools.vscode-docker
code --install-extension redhat.vscode-yaml
code --install-extension github.vscode-github-actions
code --install-extension ms-vscode-remote.remote-containers
code --install-extension gruntfuggly.todo-tree
code --install-extension esbenp.prettier-vscode
code --install-extension yzhang.markdown-all-in-one

(Optional) Apply quality‑of‑life settings via CLI by overwriting settings.json:

cat <<'EOF' > ~/Library/Application\ Support/Code/User/settings.json
{
  "editor.formatOnSave": true,
  "files.trimTrailingWhitespace": true,
  "editor.rulers": [100],
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.detectIndentation": false,
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,
  "[terraform]": { "editor.defaultFormatter": "hashicorp.terraform" },
  "terraform.languageServer": { "enabled": true },
  "makefile.configureOnOpen": true
}
EOF

Install Visual Studio Code via Chocolatey:
```
choco install vscode
```

Install recommended extensions:

hashicorp.terraform
redhat.ansible
ms-azuretools.vscode-docker
redhat.vscode-yaml
github.vscode-github-actions
ms-vscode-remote.remote-containers
ms-vscode.powershell
gruntfuggly.todo-tree
esbenp.prettier-vscode
yzhang.markdown-all-in-one

code --install-extension hashicorp.terraform
code --install-extension redhat.ansible
code --install-extension ms-azuretools.vscode-docker
code --install-extension redhat.vscode-yaml
code --install-extension github.vscode-github-actions
code --install-extension ms-vscode-remote.remote-containers
code --install-extension ms-vscode.powershell
code --install-extension gruntfuggly.todo-tree
code --install-extension esbenp.prettier-vscode
code --install-extension yzhang.markdown-all-in-one

(Optional) Apply quality‑of‑life settings via CLI by overwriting settings.json:

Set-Content "$env:APPDATA\Code\User\settings.json" @'
{
  "editor.formatOnSave": true,
  "files.trimTrailingWhitespace": true,
  "editor.rulers": [100],
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.detectIndentation": false,
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,
  "[terraform]": { "editor.defaultFormatter": "hashicorp.terraform" },
  "terraform.languageServer": { "enabled": true },
  "makefile.configureOnOpen": true
}
'@

Validation¶

Open VS Code and verify recommended extensions are installed.

🏆 Achievement Unlocked: Code editor powered up!

Exit Criteria¶

Git and GitHub CLI are installed and authenticated
Wrangler is installed and authenticated
curl is installed and validated (Windows only, macOS already includes curl)
Docker Desktop is installed and running containers successfully
Terraform is installed and validated
Ansible is installed and validated (if applicable)
Vault CLI is installed and validated
Consul CLI is installed and validated

🎉 Chapter Complete! You’ve earned up to 70 XP (like Whose Line, the points are made up but the fun is real). Onward to the next adventure!

Quick Overview

What: Shared abbreviations and hover tooltips for the campaign. Why: Ensures acronyms and jargon stay consistent across all docs. Time: Ongoing; update whenever a new term is introduced. XP: +5 per new acronym (like Whose Line, the points are made up but the fun is real).

Think of this file as your universal translator—every acronym here powers hover definitions site-wide.

🎉 Abbreviations updated! You’ve earned +5 XP for each new term (points don’t matter, but consistency does).