Skip to content

windows-setup.md

Latest commit

 

History

History
323 lines (237 loc) · 7.21 KB

windows-setup.md

File metadata and controls

323 lines (237 loc) · 7.21 KB

Windows Development Setup Guide

This guide helps you set up the ChaosLabs development environment on Windows 10/11.

Prerequisites

Required Software

  1. Git for Windows

    # Using winget (Windows Package Manager)
winget install Git.Git

# Or download from: https://git-scm.com/download/win

  2. Go 1.23+ (toolchain 1.24 as used by modules; see root go.work)

    winget install GoLang.Go
# Or: https://go.dev/dl/

  3. Node.js 20+

    # Using winget
winget install OpenJS.NodeJS

# Or download from: https://nodejs.org/

  4. Docker Desktop

    # Using winget
winget install Docker.DockerDesktop

# Or download from: https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe

Optional but Recommended

  1. Make for Windows

    # Using Chocolatey
choco install make

# Using Scoop
scoop install make

# Or use PowerShell scripts directly (see below)

  2. k6 Load Testing Tool

    # Using winget
winget install k6

# Or download from: https://github.com/grafana/k6/releases

  3. Windows Subsystem for Linux (WSL) - Alternative option

    wsl --install

Quick Setup

Method 1: Using Package Managers

Install Chocolatey (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 all dependencies

# Core dependencies
choco install git golang nodejs docker-desktop make -y

# Optional tools
choco install k6 -y

Install Winget (alternative package manager)

# Install from Microsoft Store or GitHub releases
# Then install dependencies:
winget install Git.Git GoLang.Go OpenJS.NodeJS Docker.DockerDesktop

Method 2: Manual Installation

  1. Download and install each tool from their official websites
  2. Ensure all tools are added to your PATH
  3. Restart your terminal/PowerShell

Project Setup

Clone and Setup

# Clone the repository
git clone https://github.com/fraware/chaoslabs.git
cd chaoslabs

# Run the setup script
powershell -ExecutionPolicy Bypass -File infrastructure/devtools/scripts/dev-setup.ps1

# Optional: after dependencies are installed, run `make verify` (needs golangci-lint and npm).

Verify Installation

# Check versions
go version
node --version
npm --version
docker --version
git --version

# Test Docker
docker run hello-world

Development Workflow

Using PowerShell Scripts (Recommended for Windows)

# Setup development environment
.\infrastructure\devtools\scripts\dev-setup.ps1

# Start development environment
docker compose --project-directory . -f infrastructure/docker-compose.dev.yml up

# Run quality checks
.\scripts\check-all.ps1

# Generate performance report
.\infrastructure\performance-report.ps1

# Warm up caches
.\infrastructure\cache-warming.ps1

Using Make (if installed)

From the repo root, targets include:

make tidy       # go work sync + go mod tidy in modules
make test       # controller, agent, cli tests
make verify     # tidy, lint-go, test, lint-frontend (needs golangci-lint, npm)
make integration-test   # needs Redis/NATS (see tests/integration/README.md)

See Makefile for the authoritative list.

Manual Commands

# Build Go components
cd controller
go build -o ../bin/controller.exe .
cd ../agent
go build -o ../bin/agent.exe .
cd ../cli
go build -o ../bin/chaoslabs-cli.exe .

# Build frontend
cd dashboard-v2
npm install
npm run build

# Run tests
cd controller
go test ./...
cd ../agent
go test ./...
cd ../cli
go test ./...
cd ../dashboard-v2
npm test

Common Windows Issues and Solutions

1. PowerShell Execution Policy

If you get execution policy errors:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

2. Docker Desktop Issues

  • Ensure Hyper-V is enabled
  • Make sure Docker Desktop is running
  • Check Windows features: "Containers" and "Hyper-V"
# Enable Windows features
Enable-WindowsOptionalFeature -Online -FeatureName containers -All
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

3. Path Issues

Ensure all tools are in your PATH:

# Check current PATH
$env:PATH -split ';'

# Add to PATH if needed (example for Go)
$env:PATH += ";C:\Program Files\Go\bin"

4. Long Path Support

Enable long path support for Git:

git config --global core.longpaths true

5. Line Ending Issues

Configure Git for Windows line endings:

git config --global core.autocrlf true

Alternative: WSL2 Development

If you prefer a Linux-like environment:

# Install WSL2
wsl --install

# Install Ubuntu
wsl --install -d Ubuntu

# Switch to WSL2
wsl

# Then follow the Linux setup instructions inside WSL

IDE Setup

Visual Studio Code

# Install VS Code
winget install Microsoft.VisualStudioCode

# Recommended extensions
code --install-extension golang.go
code --install-extension bradlc.vscode-tailwindcss
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension ms-vscode-remote.remote-containers

GoLand (JetBrains)

Performance Tips

  1. Use SSD storage - Significantly improves Docker and build performance
  2. Increase Docker memory - Allocate 4GB+ RAM to Docker Desktop
  3. Exclude from Windows Defender - Add project directory to exclusions
  4. Use PowerShell Core - Install PowerShell 7+ for better performance
# Install PowerShell Core
winget install Microsoft.PowerShell

Troubleshooting

Common Commands for Debugging

# Check Docker status
docker info
docker ps

# Check services
docker compose --project-directory . -f infrastructure/docker-compose.dev.yml ps

# View logs
docker compose --project-directory . -f infrastructure/docker-compose.dev.yml logs

# Reset Docker
docker system prune -a

# Clean project
Remove-Item -Recurse -Force bin, tmp, coverage

Environment Variables

# Set Go environment
$env:GOPROXY = "https://proxy.golang.org,direct"
$env:GOSUMDB = "sum.golang.org"

# Set Docker BuildKit
$env:DOCKER_BUILDKIT = "1"
$env:COMPOSE_DOCKER_CLI_BUILD = "1"

Getting help

Next steps

  1. Read the root README and docs/README.md
  2. See ARCHITECTURE.md
  3. Review CONTRIBUTING.md
  4. Run make verify from the repo root, or .\scripts\check-all.ps1 for a Windows-oriented check script