Prerequisites

These instructions are written for Windows, but should work on Linux or macOS if equivalent software is installed.

On Windows, you must use WSL2 and the latest Ubuntu distro for development. Do not save your work on the Windows C: drive. Your git repositories should be stored inside the Ubuntu WSL filesystem, for example: \\wsl.localhost\\Ubuntu-24.04\\home\\{YOUR_USERNAME}\\dev.

Install Windows software with Chocolatey or a similar package manager. Install Ubuntu packages inside WSL using the apt package manager.

Hardware

1. A recent CPU
2. At least 16 GB RAM

Windows software

1. WSL2 - "Ubuntu-24.04" as the distro
2. Windows Terminal
3. Mkcert
   • Run PowerShell as Administrator and run the command:
   • choco install mkcert
   • Allow certificates to be trusted automatically.
     • In PowerShell run mkcert.exe -install
4. Visual Studio Code - latest
   • Remote - Containers extension
   • ESLint extension
   • Prettier extension
5. Rancher Desktop for Windows
   • Rancher Desktop installs everything you need, like Docker, Docker Compose, kubectl, and Helm.
   • Preferences ➡️ Application ➡️ Behavior ➡️ select Automatically start at login and Start in the background
   • Preferences ➡️ WSL ➡️ select Ubuntu-24.04 distro
   • Preferences ➡️ Container Engine ➡️ select dockerd (moby)
   • Preferences ➡️ Kubernetes ➡️ select Enable Kubernetes
     • For the Kubernetes version, choose the latest stable version
   • Create a registries.yaml file inside the rancher-desktop WSL instance
     • In a PowerShell terminal run:

     wsl.exe -d rancher-desktop -u root -- sh -c 'cat <<EOF > /etc/rancher/k3s/registries.yaml
     mirrors:
       "localhost:5000":
         endpoint:
           - "http://localhost:5000"
     EOF'

     • To verify the registries.yaml file was created, run wsl.exe -d rancher-desktop -u root -- sh from PowerShell to open a shell in the rancher-desktop WSL instance, then run cat /etc/rancher/k3s/registries.yaml.
     • Restart Rancher Desktop for this change to take effect

WSL/Ubuntu software

1. pnpm - latest
2. NodeJS recommended to install with pnpm env - 24+
   • After installing node via pnpm env, need to install libatomic1: sudo apt update && sudo apt install libatomic1
3. Istio - 1.28+
   • Istio documentation is a little scattered, so we've summarized the commands you need below. For more information, see Ambient mode download and installation instructions with Helm on istio.io.

   helm repo add istio https://istio-release.storage.googleapis.com/charts && helm repo update
   helm install istio-base istio/base -n istio-system --create-namespace
   kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/experimental-install.yaml
   helm install istiod istio/istiod --namespace istio-system --set profile=ambient
   # Rancher Desktop uses k3s, so you need to set the platform here (https://istio.io/latest/docs/ambient/install/platform-prerequisites/#k3s)
   helm install istio-cni istio/cni -n istio-system --set profile=ambient --set global.platform=k3s
   helm install ztunnel istio/ztunnel -n istio-system

1. psql
   • sudo apt update && sudo apt install -y postgresql-client