Windows (WSL2) workstation bootstrap

<div class="getting-started-hero" markdown="1"> <h1><span class="platform-icon platform-windows"></span>Windows (WSL2) Workstation Bootstrap</h1> <h2>Standardize a Windows host + Linux (WSL2) environment for Epic on Azure engineering.</h2> <p>Best for: users needing Windows apps and Linux automation side-by-side.</p> </div> <ul class="platform-links"> <li><a class="platform-link" href="../bootstrap/">All workstation options</a></li> <li><a class="platform-link" href="macos/">macOS</a></li> <li><a class="platform-link" href="windows/">Windows (WSL2)</a></li> <li><a class="platform-link" href="windows-vdi/">Windows VDI</a></li> <li><a class="platform-link" href="saw/">SAW</a></li> </ul>

At a glance

Prerequisites

Steps

1. Enable WSL & virtualization features (PowerShell as Administrator):

   # Windows 11 (simplified)
   wsl --install
   
   # OR explicit feature enable (Windows 10/controlled hosts)
   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
   

2. Reboot when prompted.

3. Install a Linux distribution (Ubuntu LTS recommended):

   wsl --list --online
   wsl --install -d Ubuntu-22.04
   

4. Launch the distribution (first run prompts for UNIX username/password—non-privileged user is fine).

5. Update base packages inside WSL:

   sudo apt update && sudo apt -y upgrade
   sudo apt install -y git curl unzip jq ca-certificates
   

6. (Certificates) Import corporate CAs (from include docs) inside WSL:

   # Root CA (example — paste cert body from include page if not centrally managed)
   sudo tee /usr/local/share/ca-certificates/OptumRootCA.crt < ~/OptumRootCA.crt >/dev/null
   sudo update-ca-certificates
   

   See: Root CA and Internal Policy CA.

   Certificate fingerprint verification (integrity):

   openssl x509 -in /usr/local/share/ca-certificates/OptumRootCA.crt -noout -sha256 -fingerprint
   # Compare against published fingerprint in corporate trust store
   

7. Install tooling (choose package or manual):

   • Git (already if step 5 installed)

   • Terraform (manual recommended for version pin):

     TF_VERSION=1.7.5
     curl -fsSLO https://releases.hashicorp.com/terraform/${TF_VERSION}/terraform_${TF_VERSION}_linux_amd64.zip
     sudo unzip terraform_${TF_VERSION}_linux_amd64.zip -d /usr/local/bin/
     terraform -version
     

   • Azure CLI (Microsoft repository):

     curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
     az version | jq -r '."azure-cli"'
     

   • Ansible (use pipx to isolate):

     sudo apt install -y python3-pip python3-venv
     python3 -m pip install --user pipx
     python3 -m pipx ensurepath
     pipx install ansible-core==2.14.0
     ansible --version | head -1
     

   • GitHub CLI:

     type -p curl >/dev/null || sudo apt install -y curl
     curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
     sudo chmod go+r /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 -y gh
     gh --version | head -1
     

   • Packer (if image building required):

     PACKER_VERSION=1.9.4
     curl -fsSLO https://releases.hashicorp.com/packer/${PACKER_VERSION}/packer_${PACKER_VERSION}_linux_amd64.zip
     sudo unzip packer_${PACKER_VERSION}_linux_amd64.zip -d /usr/local/bin/
     packer version
     

8. Generate SSH key (if absent):

   test -f ~/.ssh/id_ed25519 || ssh-keygen -t ed25519 -C "<email>"
   

9. Azure authentication:

   az login --tenant optum.com
   az account show --output table
   

10. Record versions (see verification section) and compare with minimum table.

Verification

Run the following commands and confirm each prints a version; none report "command not found":

```bash
ansible --version | head -1
az version --output json | jq -r '."azure-cli"'
terraform version | head -1
gh --version | head -1
packer version || echo "Packer not installed yet"
```

Minimum tool versions

Troubleshooting

| Symptom | Possible cause | Resolution |
|---------|----------------|----------|
| `wsl --install` fails | Disabled virtualization | Enable virtualization in BIOS/UEFI; verify with Task Manager → Performance. |
| Slow DNS inside WSL | Windows DNS proxy conflict | Add `options rotate` to `/etc/resolv.conf`; or enable WSL systemd resolved (Win11 22H2+ feature). |
| Certificate errors | CA not trusted | Re-run CA install; confirm file in `/usr/local/share/ca-certificates/` and run `sudo update-ca-certificates`. |
| `az login` device code loop | Proxy intercept | Set `HTTPS_PROXY` and retry; test with `curl https://management.azure.com`. |

Rollback and cleanup

Security notes

Notes

• For enterprise environments add: proxy exports in shell profile, centralized log forwarder, vulnerability scanner agent.
• No proprietary locations referenced.

{{ doc_footer(page) }}