Configuração base para programação: Debian 12 e Ubuntu no WSL

Roteiro para preparar uma máquina nova. No Debian, usar o terminal Linux. No Windows 11, executar os comandos dentro do Ubuntu no WSL 2. Se necessário, começar pela instalação do WSL.

1. Instalar as ferramentas básicas

Terminal Linux · Debian ou Ubuntu

sudo apt update
sudo apt upgrade
sudo apt install -y curl ca-certificates git unzip nano zsh
mkdir -p ~/projetos

Configurar a autoria dos commits, substituindo os dados:

Terminal Linux

git config --global user.name "Seu nome"
git config --global user.email "seu-email@example.com"

2. Configurar Zsh e Oh My Zsh

Executar o instalador oficial e aceitar Zsh como shell padrão:

Terminal Linux

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Se a troca não acontecer, executar chsh -s "$(command -v zsh)" e entrar novamente na sessão. Abrir Zsh no terminal atual com zsh antes de continuar.

3. Instalar Node e npm

Instalar NVM e Node 24. npm já vem junto.

Terminal Linux · Zsh

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | PROFILE="$HOME/.zshrc" bash
source ~/.zshrc
nvm install 24
nvm alias default 24
nvm use 24
node --version
npm --version

Em projetos com .nvmrc, usar a versão indicada pelo arquivo. Não usar sudo com npm.

4. Instalar PHP 8.4, extensões, Composer e Laravel

Usar o instalador indicado pelo Laravel, selecionando PHP 8.4. Ele instala o binário do Herd Lite, Composer e o comando global laravel, tanto no Debian quanto no Ubuntu do WSL:

Terminal Linux

/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"

Reabrir o terminal e conferir:

Terminal Linux

php -v
command -v php
php -m
composer --version
laravel --version

O resultado deve indicar PHP 8.4.x e o executável em ~/.config/herd-lite/bin/php.

Extensões da máquina de referência

Na máquina usada para este roteiro, o comando php utiliza PHP 8.4.1 do Herd Lite. Os módulos abaixo foram conferidos com php -m e também aparecem com php -n -m, que ignora o php.ini: eles já estão embutidos nesse binário. Assim, a instalação acima fornece PHP com extensões, sem precisar de um comando separado para cada uma.

bcmath, bz2, calendar, Core, ctype, curl, date, dba, dom, exif,
FFI, fileinfo, filter, ftp, gd, gettext, gmp, hash, iconv,
igbinary, imagick, imap, intl, json, ldap, libxml, mbstring,
mongodb, mysqli, mysqlnd, openssl, pcntl, pcre, PDO, pdo_mysql,
pdo_pgsql, pdo_sqlite, pgsql, Phar, posix, random, readline,
redis, Reflection, session, shmop, SimpleXML, soap, sockets,
sodium, SPL, sqlite3, standard, sysvmsg, sysvsem, sysvshm,
tokenizer, xml, xmlreader, xmlwriter, xsl, zip, zlib, zstd

Essa lista inclui as extensões exigidas pelo Laravel, como ctype, curl, dom, fileinfo, filter, hash, mbstring, openssl, pcre, PDO, session, tokenizer e xml. Também inclui drivers para MySQL, PostgreSQL e SQLite, além de Redis, MongoDB, GD, Imagick, Intl, BCMath e ZIP. As extensões adicionais dependem das necessidades de cada projeto.

A lista pode variar entre atualizações do binário. Conferir com php -m após instalar e, em um projeto com as dependências instaladas, executar composer check-platform-reqs para verificar os requisitos reais.

Se houver outra instalação de PHP via APT, conferir sempre command -v php: os pacotes php8.4-* do sistema não adicionam extensões ao binário do Herd Lite.

Se PHP e Composer já estiverem instalados, adicionar apenas o instalador Laravel com composer global require laravel/installer.

5. Instalar PhpStorm

Debian

Com Snap configurado:

Terminal do Debian

sudo snap install phpstorm --classic
snap run phpstorm

Verificar a compatibilidade da versão com Debian 12: os requisitos atuais do PhpStorm listam Debian 13.

Windows com WSL

Instalar PhpStorm no Windows pelo JetBrains Toolbox. Abrir a pasta do projeto no Ubuntu e configurar o interpretador PHP via WSL.

6. Instalar Docker

Debian

Para um ambiente novo de desenvolvimento, usar o script oficial do Docker. Conferir o script baixado antes de executá-lo:

Terminal do Debian

curl -fsSL https://get.docker.com -o /tmp/get-docker.sh

Depois de conferir o arquivo:

Terminal do Debian

sudo sh /tmp/get-docker.sh
sudo docker version

Windows com WSL

Instalar Docker Desktop, ativar o backend WSL 2 e habilitar Ubuntu em Settings → Resources → WSL Integration. Manter Docker Desktop aberto. Não instalar outro Docker Engine dentro do Ubuntu.

Terminal do Ubuntu no WSL

docker version

O resultado deve mostrar Client e Server. Nos próximos comandos, adicionar sudo antes de docker se o Debian exigir essa permissão.

7. Criar MySQL no Docker

Se mysql_dev já existir, reutilizar a configuração existente. Para um container novo, criar um arquivo local com as senhas:

Terminal Linux

nano ~/mysql-dev.env

Colar o conteúdo abaixo e substituir os valores por senhas próprias:

Arquivo ~/mysql-dev.env

MYSQL_ROOT_PASSWORD=SUA_SENHA_ROOT
MYSQL_PASSWORD=SUA_SENHA_DEV

Salvar no Nano com Ctrl+O → Enter e sair com Ctrl+X. Manter esse arquivo fora do Git.

Criar o container usando a imagem oficial MySQL:

Terminal Linux · no Debian, usar sudo se necessário

docker run -d \
  --name mysql_dev \
  --restart unless-stopped \
  -p 127.0.0.1:3306:3306 \
  --env-file "$HOME/mysql-dev.env" \
  -e MYSQL_DATABASE=desenvolvimento \
  -e MYSQL_USER=dev \
  -v mysql_dev_data:/var/lib/mysql \
  mysql:8.4

docker logs --tail=40 mysql_dev

Aguardar ready for connections. O volume mysql_dev_data guarda os dados; não apagá-lo para corrigir erros de conexão. As senhas só são aplicadas na primeira inicialização de um volume vazio.

8. Instalar HeidiSQL e conectar

Baixar pela página oficial: versão Windows no Windows ou pacote Linux compatível com Debian 12 no Debian.

Criar uma sessão MySQL / MariaDB por TCP/IP:

• Host: 127.0.0.1
• Porta: 3306
• Usuário: dev
• Senha: o valor definido em MYSQL_PASSWORD
• Banco: desenvolvimento

Conectar e conferir se o banco aparece.

9. Configurar os aliases

Terminal Linux · Zsh

nano ~/.zshrc

Acrescentar ao final do arquivo, depois do carregamento do Oh My Zsh. Preservar as configurações existentes de NVM e PHP:

Arquivo ~/.zshrc

# PhpStorm: apenas para instalação Linux via Snap
alias pstorm='snap run phpstorm'

# npm
alias ni='npm install'
alias nrd='npm run dev'
alias nrb='npm run build'

# Laravel
alias pa='php artisan'
alias pas='php artisan serve'
alias pak='php artisan key:generate'
alias pam='php artisan migrate'
alias pamf='php artisan migrate:fresh'
alias pamfs='php artisan migrate:fresh --seed'

# Git
alias g='git'
alias go='git checkout'
alias pull='git pull'
alias push='git push'
alias gf='git fetch --all'

# Composer e Docker
alias ci='composer install'
alias d='docker'

Salvar e recarregar:

Terminal Linux · Zsh

source ~/.zshrc

Usar os atalhos na pasta do projeto. pamf e pamfs apagam as tabelas do banco configurado; reservar para bancos locais descartáveis. pak gera a chave da aplicação e não deve ser executado a cada início de trabalho.

Os comandos foram revisados na documentação indicada. A instalação completa não foi testada nas duas plataformas.