Dev containers: o devcontainer.json como ambiente de desenvolvimento reproduzível

O que é

A Development Container Specification se define como uma especificação aberta para enriquecer contêineres com conteúdo e configurações específicos de desenvolvimento. Os metadados ficam em .devcontainer/devcontainer.json: uma image ou build.dockerfile (ou dockerComposeFile em configurações com vários serviços), features (etapas de instalação reutilizáveis, como um toolchain de linguagem ou uma CLI, referenciadas por caminho de registry), forwardPorts, containerEnv e remoteEnv, remoteUser, customizations para configurações específicas do editor e comandos de ciclo de vida. A referência documenta a ordem deles: initializeCommand é executado no host; dentro do contêiner, onCreateCommand, updateContentCommand e postCreateCommand concluem a configuração quando o contêiner é criado; postStartCommand é executado a cada inicialização e postAttachCommand sempre que uma ferramenta se conecta. A documentação do GitHub chama o devcontainer.json de arquivo principal da configuração do Codespaces, e a referência observa que serviços na nuvem podem executar os comandos da fase de criação ao fazer cache ou pré-build de um contêiner; por isso, esses comandos normalmente não têm acesso a segredos associados ao usuário.

Por que importa

"Funciona na minha máquina" costuma ser um problema de versão do toolchain. Um dev container fixa o sistema operacional, o runtime e as ferramentas de CLI em um único arquivo versionado junto com o código; um recém-chegado, um workspace hospedado e um agente de código partem todos da mesma imagem, e não do que quer que o host tenha instalado. Como o CI pode executar a mesma imagem, o ambiente local e o pipeline deixam de divergir.

Como aplicar

• Comece por um Dockerfile em que você já confie (a imagem base de produção, quando fizer sentido) em vez de uma imagem grande do tipo tudo-em-um; adicione ferramentas por meio de features para que a lista continue legível.
• Coloque a instalação de dependências em postCreateCommand e o trabalho leve a cada inicialização (subir um serviço local, imprimir a lista de portas) em postStartCommand; mantenha os comandos da fase de criação idempotentes, já que os pré-builds podem executá-los com antecedência.
• Encaminhe apenas as portas de que a aplicação precisa e defina remoteUser como um usuário não root, para que os arquivos criados no workspace montado por bind mount tenham propriedade adequada.
• Mantenha customizations no mínimo: o formatador, as extensões recomendadas, nada pessoal.
• Reconstrua o contêiner do zero no CI de forma periódica, para detectar a deriva da imagem base e comprovar que o build da configuração ainda funciona.

Armadilhas

Um dev container não substitui um lock file: a imagem fixa o toolchain, não as dependências do projeto. Quando o bind mount do workspace é lento (algo comumente relatado com o Docker Desktop no macOS e no Windows em árvores de arquivos grandes), a propriedade workspaceMount da referência substitui a montagem padrão, por exemplo por um volume nomeado. Segredos não devem ser embutidos na imagem nem em containerEnv; forneça-os no momento da conexão (attach). Docker-in-Docker dentro do contêiner é uma feature com seus próprios trade-offs, não um padrão.