📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Guia de Ferramentas. Recomendado revisar antes de começar.

🛠️ Ambientes Reprodutíveis com DevContainers & Makefiles

v1.0 — DevContainers W3C, Docker, Automação de Tarefas com Make e Ambientes Herméticos

Trilha de Especialização Pedagógica — Projeto 1 de 4

• ➡️ v1 (este): Ambientes Reprodutíveis · DevContainers · Docker · Makefile Canônico
• v2: Gerenciamento de Segredos com Vault & SOPS
• v3: CLI Customizado em Rust/Go para Automação Interna de Equipes
• v4: Platform Engineering: Developer Portal com Backstage

🎓 Nível Profissional Simulado: Engenheiro DevOps / Platform Engineer Trainee. O dilema “na minha máquina funciona” acabou. Empresas modernas utilizam DevContainers e Makefiles, garantindo que um novo desenvolvedor consiga clonar o repositório e rodar o projeto em 30 segundos, exatamente com as mesmas versões de compilador e dependências de produção.

🎯 Objetivo & Escopo do Projeto

Criar a infraestrutura de Ambiente Reprodutível de Desenvolvimento utilizando a especificação aberta DevContainers (.devcontainer/devcontainer.json), isolamento com Docker e automação padronizada de comandos operacionais (make build, make test, make lint, make run) através de um Makefile Canônico.

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Tech Lead & Coordenador de Engenharia)

“Levamos 3 dias para configurar o computador de um novo desenvolvedor contratado porque cada um usa um sistema operacional diferente (Windows, Mac, Ubuntu) com versões conflitantes do Java, Node e Python. Queremos que qualquer desenvolvedor abra o VS Code, clique em ‘Reopen in Container’ e tenha o ambiente 100% pronto com todas as extensões instaladas e possa rodar o projeto simplesmente digitando make run.”

Requisitos Funcionais (RF) e Não-Funcionais (RNF)

📋 Fase 2 — Backlog & User Stories

🌿 Fase 3 — Engenharia em Equipe (Git Flow & Execução)

# Branch da funcionalidade
git checkout -b feature/US01-devcontainer-makefile

# Executar os targets do Makefile
make build
make test

🛠️ Fase 4 — Implementação do Makefile Canônico

SHELL := /bin/bash

.PHONY: all build test clean run

all: build test

build:
	@echo "==> Compilando a aplicacao..."

test:
	@echo "==> Executando suíte de testes automatizados..."

clean:
	@echo "==> Limpando artefatos temporarios..."

run:
	@echo "==> Iniciando o servidor de desenvolvimento..."

🚀 Como Executar no Laboratório

1. Abra o terminal na pasta deste projeto

No seu editor/IDE, abra a pasta deste projeto (File > Open Folder) ou navegue via terminal:

cd tools_01_devcontainer_makefile

2. Execute a aplicação ou testes

# Executar comandos específicos da tecnologia:
python main.py # ou npm run dev / ./gradlew build

[!TIP] Dica para execução a partir da raiz do repositório: Se você abriu o repositório completo no VS Code, basta navegar até a pasta antes de executar: cd catalogo_projetos/tools_01_devcontainer_makefile`

🧭 Decisões de Arquitetura (ADRs)

• ADR 001: Adoção de DevContainers e Makefile para erradicar inconsistências de ambiente local.

🧪 Testes de Validação & Asserções

# Validar se o Makefile executa todos os alvos sem erros
make all

🏛️ Arquitetura Visual & Engenharia de Infraestrutura

O diagrama abaixo ilustra a topologia de componentes, balanceamento, esteiras de automação e observabilidade na subpasta .devcontainer/:

flowchart TD
    subgraph Config["Configuração & IaC"]
        C1["Manifestos Declarativos"] --> C2["Variáveis & Segredos"]
    end
    subgraph Orquestracao["Orquestração & Redes"]
        O1["Load Balancer / Ingress"] --> O2["Pods / Contêineres de Serviço"]
    end
    subgraph Observabilidade["Observabilidade & Segurança"]
        M1["Telemetria Prometheus / k6"] --> M2["Scanners SAST & Dashboards"]
    end
    subgraph Qualidade["Homologação & Qualidade"]
        Q1["Automação CI/CD"] --> Q2["Checkpoints CP-01..05 PASS"]
    end

    Config --> Orquestracao
    Orquestracao --> Observabilidade
    Observabilidade --> Qualidade

    style Config fill:#e3f2fd,stroke:#1976d2,stroke-width:1.5px
    style Orquestracao fill:#fffde7,stroke:#fbc02d,stroke-width:1.5px
    style Observabilidade fill:#e8f5e9,stroke:#388e3c,stroke-width:1.5px
    style Qualidade fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px

🎯 Engenharia de Requisitos & Modelagem Formal

👤 User Stories (Histórias de Usuário)

⚙️ Requisitos Funcionais (RF)

🛡️ Requisitos Não-Funcionais (RNF)

🔗 Matriz de Rastreabilidade (RTM)

🏁 Checkpoints de Qualidade & Homologação