wsl-starter-script

Modular, idempotent bootstrap for a fresh Ubuntu WSL image. One command takes a daily Ubuntu rootfs from cloud-images.ubuntu.com/wsl — root-only, auto-login as root — and turns it into a development box with a sudo user, modern CLI, language runtimes (mise), and Claude Code.

Replaces my older base and dev-tools gists with one re-runnable installer.

Quick start

On a fresh WSL distro (still as root):

bash <(curl -fsSL https://raw.githubusercontent.com/artislismanis/wsl-starter-script/main/bootstrap.sh) --all

Or interactively — drop --all for a menu. The full walk-through (creating the distro from PowerShell, picking modules, reopening as the new user) is in docs/tutorials/getting-started.md.

What you get

• systemd, non-root sudo user, hostname, DNS, sensible /etc/wsl.conf defaults
• Modern CLI: rg, fd, bat, eza, gh, tmux, jq, plus zsh + oh-my-zsh
• atuin shell history, zoxide directory jumping
• mise + Node + Python (Ruby/Java/Go/Deno/Bun on request) + uv
• Claude Code with a starter ~/.claude/ config
• Optional: Docker Engine (classic or rootless with pasta networking), Podman

docs/reference/tools.md has the per-module breakdown — every package, what it replaces, why it earned a slot on your $PATH.

Why

A daily rootfs is the cleanest base for a dev box, but a useful one needs ~30 manual steps that are easy to fat-finger. Each module here is idempotent (re-runnable), dry-runnable (--dry-run is total), and reversible (--rollback emits a shell-pasteable unwind recipe). No framework, no Python, no hidden remote chains — pure bash, every install step lives in a checked-in module file you can read.

Documentation

Full index in docs/.

Need	Start here
First time — walk me through it	docs/tutorials/getting-started.md
Just installing	docs/how-to/install.md
Docker / rollback / host config / running tests	docs/how-to/
Look up a flag or env var	docs/reference/flags.md, env-vars.md
What's actually installed	docs/reference/tools.md
Why the project is shaped this way	docs/explanation/design.md

Working on the repo (adding a module, changing a helper)? CLAUDE.md is the contributor-facing companion — internal helper roster, module contract, write-site discipline.

Contributing

./dev-setup.sh           # apt-installs bats, shellcheck, dos2unix; enables the pre-commit hook
./lint.sh                # bash -n + shellcheck on every shell file
./tests/tier1/run.sh     # Tier 1 bats suite

The runtime install needs nothing beyond stock Ubuntu bash. The contributor extras (bats for Tier 1 tests, shellcheck for lint.sh, dos2unix for the pre-commit CRLF guard) sit outside that line — lint.sh no-ops shellcheck gracefully when it's missing, but the bats suite and the editor PostToolUse hook do need it. docs/how-to/testing.md covers the test tiers in detail.