WSL2 & Linux Dev Environment

Setup automatizado de ambiente de desenvolvimento Laravel + Claude Code para WSL2 Ubuntu e Ubuntu nativo. Inclui acesso remoto (SSH + Tailscale) e dotfiles portaveis.

Quick Start

npx @henryavila/wsl-dev-setup

TUI interativa que detecta o que ja esta instalado, pergunta o que configurar e executa tudo.

Funciona em:

• WSL2 Ubuntu — setup completo com integracao Windows
• Ubuntu nativo — infra, remote access e dotfiles
• Windows — prerequisite check e bootstrap do WSL

CLI

npx @henryavila/wsl-dev-setup           # TUI interativa (default: setup)
npx @henryavila/wsl-dev-setup status     # Mostra o que esta instalado
npx @henryavila/wsl-dev-setup services   # Gerencia servicos (MySQL, Redis, etc.)

Arquitetura: 3 camadas

| Camada | Script | O que faz | Quando rodar | |--------|--------|-----------|-------------| | 1. Infra | setup.sh | Instala PHP, Node, MySQL, Redis, Nginx, Claude Code, CLI tools | 1x por maquina nova | | 2. Remote Access | remote-access/ | SSH, Tailscale, tmux, Mosh, auto-start | 1x por maquina nova | | 3. Configs | deploy-dotfiles.sh | Aplica bashrc, inputrc, tmux.conf, starship, typora-wait, gitconfig | Sempre que mudar algo |

Fluxo: maquina nova

Via npx (recomendado):

npx @henryavila/wsl-dev-setup

A TUI orquestra as 3 camadas automaticamente.

Via git clone (para customizar templates):

1. Instalar WSL2 + Ubuntu (ou Ubuntu nativo)
2. git clone https://github.com/henryavila/wsl-dev-setup.git ~/.wsl-setup
3. bash ~/.wsl-setup/setup.sh
4. (WSL) No PowerShell do Windows:
   PowerShell -ExecutionPolicy Bypass -File \\wsl$\Ubuntu\home\<user>\.wsl-setup\remote-access\setup-windows.ps1
5. bash ~/.wsl-setup/deploy-dotfiles.sh

Fluxo: atualizar configs

1. Editar o template em ~/.wsl-setup/templates/
2. bash ~/.wsl-setup/deploy-dotfiles.sh
3. cd ~/.wsl-setup && git add -A && git commit -m "update bashrc" && git push
4. Outro PC: cd ~/.wsl-setup && git pull && bash deploy-dotfiles.sh

Camada 1: Infra (setup.sh)

Script interativo (TUI via dialog) que detecta o que ja esta instalado e configura o que falta.

Core

• PHP + extensoes + Composer
• Node.js + npm
• MySQL + Redis
• Nginx catch-all + PHP-FPM (*.localhost domains)
• Claude Code + sandbox (bubblewrap, socat)
• Git configurado + SSH key

Servicos opcionais

PostgreSQL, MinIO, Mailpit, Meilisearch, Xdebug, Supervisor, mkcert

CLIs opcionais

GitHub CLI, WP-CLI, Laravel Installer, ngrok, lazygit, jq, mycli, pgcli, bun

Terminal UX (opcional)

Starship (prompt), ble.sh (autosugestoes), eza (ls), bat (cat), fzf (fuzzy finder), zoxide (cd inteligente), delta (git diff), fd (find) + Catppuccin Mocha tema + CaskaydiaCove Nerd Font

Camada 2: Remote Access

Acesso ao terminal de qualquer lugar (iPad, iPhone, outro PC) sem desktop remoto.

WSL2 — rodar no PowerShell do Windows (o script chama setup-wsl.sh internamente):

PowerShell -ExecutionPolicy Bypass -File \\wsl$\Ubuntu\home\<user>\.wsl-setup\remote-access\setup-windows.ps1

Ubuntu nativo — executado automaticamente pela TUI, ou manualmente:

bash remote-access/setup-linux-host.sh

O que e instalado:

• SSH server + chave Ed25519
• Tailscale (VPN mesh)
• tmux + Mosh
• Sudoers sem senha
• (WSL) .wslconfig, systemd, Task Scheduler auto-start

Detalhes em remote-access/README.md e remote-access/guia-uso.md.

Camada 3: Configs (deploy-dotfiles.sh)

Aplica os templates nos destinos corretos. Compara antes de sobrescrever e faz backup automatico.

Templates e destinos

| Template | Destino | Conteudo | |----------|---------|----------| | templates/bashrc | ~/.bashrc | Shell completo: ble.sh, starship, aliases, tools, editor, history | | templates/inputrc | ~/.inputrc | Readline: Ctrl+Arrow, history search, autocomplete | | templates/tmux.conf | ~/.tmux.conf | Prefix Ctrl+A, mouse, splits, status bar | | templates/starship.toml | ~/.config/starship.toml | Prompt com git, linguagens, tempo | | templates/typora-wait | ~/.local/bin/typora-wait | Wrapper WSL para Typora como $EDITOR | | templates/gitconfig.template | ~/.gitconfig (merge) | Delta, merge, diff (preserva [user] e [credential]) |

Customizacao por maquina

Criar ~/.bashrc.local para overrides locais (nao compartilhados entre maquinas). Carregado automaticamente pelo bashrc template.

# Exemplo ~/.bashrc.local
export TYPORA_PATH="/mnt/c/Caminho/Customizado/Typora.exe"
alias proj='cd ~/code/web/meu-projeto'

Pre-requisitos

• WSL2: Windows 10/11 com WSL2 + Ubuntu (wsl --install -d Ubuntu-24.04)
• Linux nativo: Ubuntu 22.04+
• Via npx: Node.js 18+

Apos o setup

• ~/INSTALLED.md — referencia de tudo que foi instalado
• ~/start-services.sh — inicia MySQL, Redis, Nginx, PHP-FPM
• ~/link-project.sh — linka subprojetos no nginx (~/code/web/nome/public → nome.localhost)
• Chave SSH: cat ~/.ssh/id_ed25519.pub (adicionar no GitHub)

Backup/Restore (WSL)

wsl --export Ubuntu-24.04 D:\backups\wsl-ubuntu-backup.tar
wsl --import Ubuntu-24.04 C:\wsl\Ubuntu D:\backups\wsl-ubuntu-backup.tar

Regra de ouro (WSL): Nunca trabalhe em /mnt/c/ ou /mnt/d/ — performance 10-50x pior. Use o filesystem nativo: ~/code/web/.

Estrutura do projeto

@henryavila/wsl-dev-setup
├── src/                        # TypeScript (Ink/React TUI)
│   ├── cli.ts                  # Entry point
│   ├── detect.ts               # Deteccao de ambiente
│   ├── execute.ts              # Orquestra execucao dos scripts
│   ├── plan.ts                 # Gera plano de instalacao
│   ├── commands/               # Subcomandos (status, services)
│   ├── screens/                # Telas da TUI
│   └── ui/                     # Componentes React/Ink
├── dist/                       # Build compilada (entry point via npx)
├── setup.sh                    # Camada 1: instala software
├── deploy-dotfiles.sh          # Camada 3: aplica configs
├── scripts/
│   ├── detect.sh               # Deteccao de ambiente (bash)
│   └── detect-windows.ps1      # Deteccao de ambiente (PowerShell)
├── templates/
│   ├── bashrc                  # → ~/.bashrc
│   ├── inputrc                 # → ~/.inputrc
│   ├── tmux.conf               # → ~/.tmux.conf
│   ├── starship.toml           # → ~/.config/starship.toml
│   ├── typora-wait             # → ~/.local/bin/typora-wait
│   ├── gitconfig.template      # → ~/.gitconfig (merge)
│   ├── terminal-ux.bashrc      # Bloco injetado pelo setup.sh (fallback)
│   ├── start-services.sh       # → ~/start-services.sh
│   └── link-project.sh         # → ~/link-project.sh
├── remote-access/              # Camada 2: SSH + Tailscale + tmux
│   ├── setup-windows.ps1       # Entry point WSL (chama setup-wsl.sh)
│   ├── setup-wsl.sh            # Setup dentro do WSL
│   ├── setup-linux-host.sh     # Setup para Ubuntu nativo
│   ├── validate.ps1            # Validacao pos-setup
│   ├── README.md
│   └── guia-uso.md
├── package.json                # npm: @henryavila/wsl-dev-setup
├── quick-reference.md          # Comandos do dia a dia
└── README.md

Documentacao

• docs/terminal-personalization.md — guia completo de cada ferramenta terminal
• quick-reference.md — comandos do dia a dia e troubleshooting
• remote-access/guia-uso.md — workflow de acesso remoto, tmux, Tailscale