Ficha 02 · Markdown, Git e tipos especiais
- Usar Markdown
- Versionar docs com Git
- Escrever runbook
- Escrever post-mortem
Parte I · Markdown
Exercício 1 · Sintaxe (15 pts)
Escreve em Markdown:
a) Um título de nível 2 com texto "Procedimento".
b) Uma lista numerada com 3 passos.
c) Um link com texto "ver docs" apontando para https://aulify.pt/docs.
d) Uma palavra em negrito dentro de uma frase.
e) Uma tabela com 2 colunas (Comando, Função) e 2 linhas de exemplo.
a) ## Procedimento
b)
1. Primeiro passo
2. Segundo passo
3. Terceiro passo
c) [ver docs](https://aulify.pt/docs)
d) Configurar **firewall** antes de tudo.
e)
| Comando | Função |
|---|---|
| ls | Listar ficheiros |
| cd | Mudar directoria |
Exercício 2 · Conversões com Pandoc (10 pts)
Escreve o comando Pandoc para:
a) Converter manual.md em PDF.
b) Converter manual.md em DOCX.
c) Converter manual.md em HTML com CSS personalizado style.css.
a) pandoc manual.md -o manual.pdf
b) pandoc manual.md -o manual.docx
c) pandoc manual.md -c style.css -o manual.html (ou --css style.css)
Parte II · Git para docs
Exercício 3 · Workflow (15 pts)
Estás a manter documentação num repositório Git partilhado. Descreve o workflow para corrigir um erro num manual:
- Pull das últimas alterações:
git pull origin main. - Criar branch para a alteração:
git checkout -b fix/manual-typo. - Editar ficheiro com o editor preferido.
- Stage das alterações:
git add docs/manual.md. - Commit com mensagem clara:
git commit -m "fix: typo no manual de instalação". - Push do branch:
git push -u origin fix/manual-typo. - Abrir Pull Request no GitHub/GitLab.
- Aguardar revisão de outro colega.
- Após aprovação, merge para main.
Exercício 4 · Estrutura de repositório (10 pts)
Propõe uma estrutura para repositório de documentação de uma equipa de IT escolar (15 documentos diferentes: manuais, runbooks, post-mortems, API):
escola-docs/
├── README.md # entrada, links a tudo
├── manuais/
│ ├── moodle-utilizador.md
│ ├── wifi-aluno.md
│ └── email-professor.md
├── runbooks/
│ ├── restart-moodle.md
│ ├── restore-backup.md
│ └── adicionar-utilizador-ad.md
├── post-mortems/
│ └── 2026-05-incidente-rede.md
├── api/
│ └── openapi.yaml
├── arquitectura/
│ └── topologia-rede.md
└── CHANGELOG.md
Vantagens: organização por tipo, fácil descobrir, permite owners por pasta.
Parte III · Runbook
Exercício 5 · Escrever runbook (20 pts)
Escreve um runbook para reiniciar o servidor Moodle quando os utilizadores reportam lentidão.
Inclui verificações antes e depois, e critérios de rollback se algo correr mal.
# Runbook · Restart Moodle
**Quando usar:** utilizadores reportam lentidão; CPU ou RAM no servidor > 90%.
**Tempo estimado:** 5 minutos. Downtime: ~2 minutos.
## Pré-verificações
1. `ssh admin@moodle-srv-01`
2. Verificar carga: `uptime`
- Se load average > 8 → continuar.
3. Verificar disco: `df -h`
- Se > 95% → não reiniciar, ir para runbook "limpar logs Moodle".
4. Avisar utilizadores no canal #escola-it.
## Reiniciar
5. Parar Apache: `sudo systemctl stop apache2`
6. Parar MySQL: `sudo systemctl stop mysql`
7. Aguardar 10 segundos.
8. Arrancar MySQL: `sudo systemctl start mysql`
9. Verificar status: `sudo systemctl status mysql`
- Deve estar "active (running)".
10. Arrancar Apache: `sudo systemctl start apache2`
## Verificação pós-restart
11. `curl -I https://moodle.escola.pt/login`
- Esperado: `HTTP/2 200`.
12. Login via browser com conta de teste.
13. Verificar load: `uptime` (deve baixar nos próximos 2 min).
## Rollback
Se o site não carregar após 3 minutos:
- Verificar logs: `tail -50 /var/log/apache2/error.log`
- Restaurar configuração anterior: `cp /etc/apache2/apache2.conf.bak /etc/apache2/apache2.conf`
- Reiniciar: `sudo systemctl restart apache2`
- Se ainda falhar, escalar para o supervisor.
Parte IV · Post-mortem
Exercício 6 · Escrever post-mortem (15 pts)
Cenário: ontem (18 Maio 2026) das 14h às 16h o Moodle ficou em baixo. Investigaram e descobriram que um técnico fez UPDATE sem WHERE numa tabela users em produção, alterando 12000 contas. Restauraram do backup das 13h. Perderam-se 1h de trabalho de alunos.
Escreve um post-mortem completo (timeline, causa, lições, acções):
# Post-mortem · Moodle indisponível 14h-16h
**Data do incidente:** 18 de Maio de 2026
**Duração:** 2h00 (14h00 - 16h00)
**Impacto:** 12 000 utilizadores afectados, 1h de dados perdida.
**Severidade:** Sev 1 (sistema crítico em produção).
## Resumo
Um `UPDATE` sem cláusula `WHERE` em ambiente de produção alterou 12 000 contas
da tabela `users`. Detectado às 14h05 por alertas de monitorização. Restauro
do backup das 13h00 completo às 16h00.
## Timeline
| Hora | Evento |
|---|---|
| 13h00 | Backup automático completo. |
| 13h58 | Técnico A executa script de manutenção em phpMyAdmin. |
| 14h00 | UPDATE incorrecto executado (sem WHERE). |
| 14h05 | Alertas: 4000+ logins falhados em 5 minutos. |
| 14h12 | IT identifica problema na BD. |
| 14h25 | Decisão: rollback para backup das 13h. |
| 14h30 | Comunicação aos professores: "incidente em curso". |
| 15h15 | Backup restaurado em ambiente de staging. |
| 15h45 | Restauro em produção iniciado. |
| 16h00 | Moodle operacional. Login validado.|
## Causa raiz
1. Script executado directamente em produção sem revisão por par.
2. Cláusula `WHERE` esquecida ao adaptar query.
3. Sem ambiente de staging para testar primeiro.
4. Permissões da conta `admin` sem restrições de operações em massa.
## O que correu bem
- Monitorização detectou em 5 minutos.
- Backup das 13h disponível e íntegro.
- Restauro foi suave sem complicações técnicas.
- Comunicação aos professores foi rápida e clara.
## O que correu mal
- 1h de trabalho perdido pelos utilizadores.
- Script de produção sem revisão prévia.
- Sem ambiente de staging dedicado.
- Sem dry-run obrigatório para queries massivas.
## Acções correctivas
| Acção | Responsável | Prazo |
|---|---|---|
| Bloquear execução directa em prod sem PR | Equipa IT | 1 semana |
| Implementar staging idêntico a prod | João S. | 1 mês |
| Política: queries em massa requerem 2ª aprovação | Coordenador IT | 1 semana |
| Backup horário (em vez de diário) | Maria L. | 2 semanas |
| Workshop interno "como não destruir prod" | Coordenador | 2 semanas |
## Conclusão
Incidente humano com causa sistémica. Foco da correcção em **processos**, não
em sanção pessoal — o técnico seguiu a prática vigente. Os controlos serão
reforçados para que erro semelhante não volte a ter este impacto.