Complete development machine setup for PPR engineers running WSL on Windows. Use this skill when onboarding a new developer, setting up a fresh WSL instance, or diagnosing a broken dev environment. Covers SSH keys, git config, workspace layout, tools repo setup, Node.js via nvm, and WSL-specific gotchas (e.g. Windows Node.js bleeding into PATH). Always use this skill when someone says they are setting up a new machine, a new WSL environment, or asks what they need to install to get started with PPR development.
Complete setup sequence for a new PPR development machine running WSL (Ubuntu) on Windows. Work through the steps in order.
Check first:
cat /etc/os-release)curl -I https://github.com)grep oh-my-zsh ~/.zshrc)sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
ssh-keygen -t ed25519 -C "github" -f ~/.ssh/id_ed25519 -N ""
cat ~/.ssh/id_ed25519.pub
Add the public key to GitHub: Settings → SSH and GPG keys → New SSH key
Then test:
eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519
ssh -T [email protected]
# Expected: Hi <username>! You've successfully authenticated...
Persist the agent across sessions by adding this to ~/.zshrc (after the source $ZSH/oh-my-zsh.sh line):
# SSH agent
if ! pgrep -u "$USER" ssh-agent > /dev/null; then
eval "$(ssh-agent -s)"
fi
ssh-add ~/.ssh/id_ed25519 2>/dev/null
git config --global user.name "First Lastname"
git config --global user.email "[email protected]"
mkdir -p ~/ws/ppr/tech ~/ws/ppr/support
~/ws/ppr/tech/ — paperround-tech GitHub org repos~/ws/ppr/support/ — SupportPaperround GitHub org reposWindows Node.js bleeds into the WSL $PATH and breaks npm installs with UNC path errors.
Always install a native Linux Node via nvm — do this before running the tools setup script.
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
export NVM_DIR="$HOME/.nvm" && \. "$NVM_DIR/nvm.sh"
nvm install --lts
Verify it's the Linux version (path must NOT start with /mnt/c/):
which node # e.g. /home/<user>/.nvm/versions/node/v24.x.x/bin/node
node --version
nvm adds itself to ~/.zshrc automatically.
git clone [email protected]:paperround-tech/tools.git ~/ws/ppr/tech/tools
~/ws/ppr/tech/tools/scripts/setup.sh
This will:
~/.agents/skills/shell/aliases.sh source line to ~/.zshrchnddb-queriesVerify everything is green:
~/ws/ppr/tech/tools/scripts/setup.sh status
source ~/.zshrc
Check that aliases are available: zs, ta, portal-qa-tunnel, etc.
Install all required CLI tools:
sudo apt-get update && sudo apt-get install -y tig openvpn unzip wslu postgresql-client
wslu enables WSL to open URLs in the Windows default browser — required for aws sso login and gh auth login to work correctly.
Required for SSM-based database tunnels (e.g. portal-development-tunnel):
curl -fsSL "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o /tmp/session-manager-plugin.deb
sudo dpkg -i /tmp/session-manager-plugin.deb
session-manager-plugin --version
gh)sudo mkdir -p -m 755 /etc/apt/keyrings
wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null
sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/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-get update && sudo apt-get install -y gh
Then authenticate:
gh auth login
curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o /tmp/awscliv2.zip
unzip -q /tmp/awscliv2.zip -d /tmp/
sudo /tmp/aws/install
aws --version
curl -fsSL https://deno.land/install.sh | sh
export PATH="$HOME/.deno/bin:$PATH"
deno install -A --reload -f -g -n linear jsr:@schpet/linear-cli
Verify:
linear --version
Deno adds itself to ~/.zshrc automatically.
The GH_PAGER and AWS_PAGER exports are handled automatically by setup.sh (Step 5).
No manual .zshrc edits needed for those.
Most tools require AWS credentials. Configure SSO once:
aws configure sso
# Session name: paperround
# SSO start URL: https://paperround.awsapps.com/start
# SSO region: eu-west-1
# Default output: json
Daily login:
aws sso login --profile paperround
export AWS_PROFILE=paperround
See the aws-sso-manage skill for full user/permission-set details.
Windows executables in PATH: Windows node, npm, and python can shadow Linux versions.
Symptoms: commands invoke C:\Windows\system32\cmd.exe, or errors mention UNC paths
(\\wsl.localhost\...). Always install Linux-native versions (nvm for Node, apt for Python).
Line endings: If a shell script fails with bad interpreter, strip Windows CR characters:
sed -i 's/\r//' script.sh
SSH agent across sessions: The snippet added in Step 1 ensures the key is loaded on every new terminal without spawning duplicate agents.
The portal runs inside a devcontainer — not directly in WSL.
portal-DB and portal into ~/ws/ppr/tech/docker build -t db-image ~/ws/ppr/tech/portal-DB
docker network create my-network
docker run --name db-container --network my-network -d -p 5432:5432 db-image
portal/.env from .env.example — populate SSM values with the script in the tools repo,
add Azure credentials manually. Use DB_HOST=db-container (not localhost).~/ws/ppr/tech/portal in VS Code — it will prompt to reopen in devcontainerssh -T [email protected] returns successuser.name and user.email configured~/ws/ppr/tech/ and ~/ws/ppr/support/ created~/ws/ppr/tech/toolssetup.sh completed without errorssetup.sh status shows all greentig, openvpn installed via aptgh installed and authenticated (gh auth login)aws --version)linear --version)source ~/.zshrc — aliases and all CLIs available