Mentoria CREMESP · PHP Moderno — Guia de preparação do ambiente

gistfile1.txt

# Guia de preparação do ambiente

**Mentoria CREMESP · PHP Moderno com Laravel, Bootstrap 5 e CI/CD**
Trilha DevOps (semanas 1 a 6) · Instrutor: Tiago Pádua

Este guia explica o que instalar, como verificar a instalação e como criar e clonar o seu repositório do projeto **Agenda de Eventos**, que vamos evoluir ao longo das seis semanas.

| Prazo | O que precisa estar pronto |
|---|---|
| **Antes da 1ª mentoria (13/10)** | Conta no GitHub, Git configurado, repositório criado e clonado (seções 1 a 6) |
| **Antes da 2ª mentoria (20/10)** | Docker funcionando e conta no Docker Hub (seções 4 e 5) |

> **Não conseguiu instalar algo na sua máquina?** Use o **GitHub Codespaces** (seção 7): um ambiente pronto no navegador, sem instalar nada.

---

## 1. O que você vai precisar

| Item | Para quê | A partir da | Obrigatório? |
|---|---|---|---|
| Conta no **GitHub** | Repositório, pull requests, GitHub Actions | Semana 1 | Sim |
| **Git** | Versionar e enviar o código | Semana 1 | Sim |
| Editor de código (sugestão: **VS Code**) | Editar o projeto | Semana 1 | Sim |
| **PHP 8.3 ou superior** + **Composer** | Rodar a aplicação e os testes na sua máquina | Semana 1 | Recomendado |
| **Docker** (com Docker Compose) | Containers, MySQL e NGINX | Semana 2 | Sim |
| Conta no **Docker Hub** | Publicar a imagem da aplicação | Semana 2 | Sim |

---

## 2. Contas

1. **GitHub:** crie uma conta em <https://github.com/signup> (se ainda não tiver). Recomendado: ative a **autenticação em dois fatores** em *Settings → Password and authentication*.
2. **Docker Hub** (até a semana 2): crie uma conta gratuita em <https://hub.docker.com/signup>.

> Use de preferência uma conta **pessoal**. Os repositórios do treinamento serão **públicos**: não coloque senhas, tokens ou dados reais neles.

---

## 3. Escolha o seu caminho

| Caminho | Quando escolher |
|---|---|
| **A. Instalar na sua máquina** (seção 4) | Você tem permissão de administrador e pode instalar programas |
| **B. GitHub Codespaces** (seção 7) | Máquina corporativa com restrições, sem permissão de administrador, ou problemas com Docker |

> **Atenção, máquinas institucionais:** o **Docker Desktop** é gratuito para uso pessoal e educacional, mas o uso profissional em organizações grandes e órgãos públicos pode exigir licença paga. Se for usar a máquina do trabalho, confirme a política com a área de TI. Alternativas sem custo: **Codespaces**, **Docker Engine no WSL2/Linux**, **Podman Desktop** ou **Rancher Desktop**.

---

## 4. Instalação na sua máquina

### 4.1 Windows (recomendado: WSL2 + Ubuntu)

O projeto usa scripts de terminal (bash). No Windows, o caminho mais tranquilo é trabalhar dentro do **WSL2** (um Linux integrado ao Windows).

1. Abra o **PowerShell como administrador** e rode o comando abaixo. Depois, reinicie o computador.

   ```powershell
   wsl --install
   ```

2. Abra o aplicativo **Ubuntu**, crie seu usuário e senha do Linux e instale as ferramentas:

   ```bash
   sudo apt update
   sudo apt install -y git curl unzip composer \
       php-cli php-sqlite3 php-mysql php-xml php-mbstring
   ```

3. Instale o **VS Code** no Windows (<https://code.visualstudio.com/>) e a extensão **WSL**. Para abrir um projeto que está no Ubuntu, rode `code .` no terminal do Ubuntu.
4. **Docker** (semana 2), uma das opções:
   - **Docker Desktop** para Windows, com a integração com o WSL ligada (*Settings → Resources → WSL integration*).
   - **Docker Engine** instalado dentro do Ubuntu do WSL, seguindo a documentação oficial para Ubuntu.

> Trabalhe com os projetos **dentro** do Linux (ex.: `~/projetos`), e não em `C:\...`. Fica bem mais rápido e evita problemas de quebra de linha.

### 4.2 macOS

1. Instale o **Homebrew** (<https://brew.sh/>), se ainda não tiver.
2. Instale as ferramentas:

   ```bash
   brew install git php composer
   ```

3. Instale o **VS Code** (<https://code.visualstudio.com/>).
4. **Docker** (semana 2): **Docker Desktop** para Mac (escolha a versão *Apple Silicon* ou *Intel*), ou uma alternativa como Podman Desktop, Rancher Desktop ou OrbStack.

### 4.3 Linux (Ubuntu/Debian)

```bash
sudo apt update
sudo apt install -y git curl unzip composer \
    php-cli php-sqlite3 php-mysql php-xml php-mbstring
```

**Docker** (semana 2): instale o **Docker Engine** pela documentação oficial e adicione seu usuário ao grupo `docker`. Depois, saia e entre de novo na sessão:

```bash
sudo usermod -aG docker $USER
```

---

## 5. Configure o Git

Rode **uma única vez** (no Windows, dentro do Ubuntu do WSL):

```bash
git config --global user.name "Seu Nome"
git config --global user.email "seu-email@exemplo.com"   # o mesmo e-mail da conta do GitHub
git config --global init.defaultBranch main
```

**Autenticação com o GitHub.** O GitHub **não aceita a senha da conta** no `git push` via HTTPS. Escolha uma opção:

| Opção | Como |
|---|---|
| **GitHub CLI** (mais simples) | Instale o `gh` (<https://cli.github.com/>) e rode `gh auth login`, escolhendo **HTTPS** |
| **Git Credential Manager** | Já vem no Git para Windows e abre o navegador para você autorizar no primeiro `push` |
| **Chave SSH** | Siga o guia "Conectar-se ao GitHub com SSH" da documentação do GitHub |

---

## 6. Crie e clone o seu repositório

### 6.1 Crie o repositório a partir do template

1. Acesse **<https://github.com/tiagolpadua/php-moderno-agenda-eventos>**.
2. Clique em **Use this template → Create a new repository**.
3. Em *Owner*, escolha **a sua conta**. Use o nome `php-moderno-agenda-eventos` e marque **Public**.
4. Clique em **Create repository**.

> Não use "Fork": durante a trilha você vai configurar Actions, Dependabot e regras de proteção **no seu próprio repositório**.

### 6.2 Clone e rode a aplicação

Troque `SEU-USUARIO` pelo seu usuário do GitHub:

```bash
mkdir -p ~/projetos && cd ~/projetos
git clone https://github.com/SEU-USUARIO/php-moderno-agenda-eventos.git
cd php-moderno-agenda-eventos

composer install      # instala as dependências (PHPUnit)
composer test         # deve terminar com "OK (10 tests ...)"
composer serve        # sobe a aplicação em http://localhost:8000
```

Abra **<http://localhost:8000>** no navegador. Você deve ver a **Agenda de Eventos** com três eventos de exemplo. Para parar o servidor, use `Ctrl + C` no terminal.

> Sem Composer? Dá para ver a aplicação funcionando com `php -S localhost:8000 -t public`.

### 6.3 Teste o envio (push)

Confirme que você consegue enviar alterações para o seu repositório:

```bash
git switch -c teste/push
git commit --allow-empty -m "chore: teste de push"
git push -u origin teste/push
```

Se o push funcionou, a branch `teste/push` aparece no GitHub. Pode apagá-la depois: `git push origin --delete teste/push`.

---

## 7. Alternativa: GitHub Codespaces (sem instalar nada)

1. No **seu** repositório (criado na seção 6.1), clique em **Code → Codespaces → Create codespace on main**.
2. Aguarde o ambiente abrir. É um VS Code no navegador, já com o projeto clonado.
3. No terminal do Codespace, confira as ferramentas e rode a aplicação:

   ```bash
   php -v && composer --version && docker --version
   composer install && composer test
   composer serve
   ```

4. Quando a aplicação subir, o Codespaces oferece **abrir a porta 8000** no navegador (aba **Ports**).

> O plano gratuito do GitHub inclui uma **cota mensal** de uso do Codespaces. **Pare o Codespace** quando terminar (*Code → Codespaces → ⋯ → Stop codespace*) para não consumir a cota à toa.

---

## 8. Verificação final

Rode os comandos abaixo. Os resultados devem ser parecidos com estes:

| Comando | Resultado esperado | Necessário para |
|---|---|---|
| `git --version` | `git version 2.x` | Semana 1 |
| `php -v` | `PHP 8.3.x` ou superior | Semana 1 |
| `composer --version` | `Composer version 2.x` | Semana 1 |
| `docker --version` | `Docker version 2x.x` (ou superior) | Semana 2 |
| `docker compose version` | `Docker Compose version v2.x` (ou superior) | Semana 2 |
| `docker run --rm hello-world` | Mensagem "Hello from Docker!" | Semana 2 |

---

## 9. Problemas comuns

| Problema | Solução |
|---|---|
| `Authentication failed` no `git push` | O GitHub não aceita a senha da conta. Use `gh auth login`, o Git Credential Manager ou SSH (seção 5) |
| `php: command not found` | O PHP não foi instalado ou não está no PATH. Repita a seção 4, ou use o Codespaces |
| Versão do PHP menor que 8.3 | Atualize o PHP (no Ubuntu 24.04 o pacote padrão já é 8.3), ou use o Codespaces |
| `composer install` reclama de extensão faltando (`ext-...`) | Instale a extensão indicada (ex.: `sudo apt install php-xml php-mbstring`) |
| `Address already in use` na porta 8000 | Outro programa usa a porta. Rode `php -S localhost:8001 -t public` |
| Arquivos inteiros aparecem como alterados no Git (Windows) | Quebra de linha CRLF × LF. Trabalhe dentro do WSL, ou rode `git config --global core.autocrlf true` no Git para Windows |
| `permission denied ... docker.sock` (Linux/WSL) | Rode `sudo usermod -aG docker $USER`, saia e entre de novo |
| Docker Desktop não inicia no Windows | Verifique se a virtualização está ativa na BIOS e se o WSL2 está instalado (`wsl --status`) |
| Sem permissão de administrador na máquina | Use o **GitHub Codespaces** (seção 7) |

---

## 10. Checklist antes da 1ª mentoria (13/10)

- [ ] Conta no GitHub criada (com autenticação em dois fatores)
- [ ] Git instalado e configurado (`user.name`, `user.email`)
- [ ] Repositório `php-moderno-agenda-eventos` criado **a partir do template**, na sua conta, como público
- [ ] Repositório clonado, `composer test` passando e aplicação abrindo em `http://localhost:8000` (ou no Codespaces)
- [ ] `git push` funcionando (seção 6.3)
- [ ] (até 20/10) Docker instalado, `docker run --rm hello-world` funcionando e conta no Docker Hub

---

## Referências oficiais

- Git: <https://git-scm.com/downloads>
- GitHub: criar repositório a partir de um modelo: <https://docs.github.com/pt/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template>
- GitHub: credenciais no Git: <https://docs.github.com/pt/get-started/git-basics/caching-your-github-credentials-in-git>
- GitHub CLI: <https://cli.github.com/>
- GitHub Codespaces: <https://docs.github.com/pt/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository>
- WSL: <https://learn.microsoft.com/pt-br/windows/wsl/install>
- PHP: <https://www.php.net/downloads> · Composer: <https://getcomposer.org/download/>
- Docker: <https://docs.docker.com/get-started/get-docker/>
- VS Code: <https://code.visualstudio.com/>

**Dúvidas?** Traga para a mentoria ou fale com o instrutor: tiagolpadua@gmail.com