Status: Approved · v1 · SPEC-ARCH-CONTAINER-001

depends_on: SPEC-ARCH-MONOREPO-001, SPEC-ARCH-BOUNDARIES-001, SPEC-ARCH-SECURITY-001, SPEC-ARCH-OBS-001

used_by: IS-MVP-18.1, IS-MVP-18.2

Containerização e integração reproduzível

Docker torna build, integração e execução reproduzíveis; não altera boundaries nem força todos os produtos a terem o mesmo modelo de runtime.

Objetivo

Definir a containerização do monorepo para desenvolvimento, integração, smoke tests e entrega da API. O resultado deve reproduzir a instalação pnpm, respeitar o grafo Turborepo e permitir validar web, mobile e API em ambiente Linux limpo.

Escopo por alvo

Alvo	Imagem/runtime	Uso obrigatório
apps/web	imagem multi-stage de build e runtime Next.js	integração local, smoke e portabilidade; Vercel continua construindo o web a partir do monorepo
services/api	imagem multi-stage Node/NestJS	integração local, smoke e deploy em provedor compatível com container
apps/mobile	imagem de toolchain/build, sem runtime de produção	typecheck, testes e expo export; emulador, assinatura e publicação em stores ficam fora do container
packages compartilhados	stages/dependências do consumidor	nunca são imagens publicáveis isoladas

“Dockerizar todo o projeto” significa que os três alvos podem ser instalados, compilados e validados por imagens reproduzíveis. Não significa executar aplicativo iOS/Android como serviço web.

Artefatos previstos

• Dockerfiles multi-stage por alvo ou Dockerfile parametrizado com targets explícitos;
• compose.yaml para web + API e perfil opcional de validação mobile;
• .dockerignore no contexto correto;
• comandos documentados de build, up, health, logs e teardown;
• scripts de smoke determinísticos;
• validação automatizada de imagens e Compose no CI.

Regras de imagem

1. Base Linux e versões de Node/pnpm compatíveis com package.json e lockfile.
2. Instalação com lockfile imutável e cache por camadas; não copiar o monorepo inteiro antes da resolução quando isso destruir o cache sem necessidade.
3. O build inclui apenas workspaces necessários ao alvo, sem quebrar dependências workspace:*.
4. Runtime final contém somente artefatos e dependências necessários; toolchain de build não permanece sem justificativa.
5. Processo de runtime usa usuário não-root, recebe sinais e encerra de forma graciosa.
6. Imagem não contém .env, tokens, .git, caches locais, relatórios ou credenciais.
7. Tags publicáveis são imutáveis por commit SHA; latest não é fonte de rollback.
8. Build deve funcionar em linux/amd64; multiplataforma adicional só entra com consumidor real.

Compose de integração

O perfil padrão sobe:

• API em 4000, com healthcheck GET /api/v1/health;
• web em 3000, configurado para consumir a API exposta pelo host/rede de integração;
• rede isolada e nomes de serviço estáveis;
• volumes apenas para cache/dev quando necessários, nunca para simular persistência que o domínio ainda não possui.

O web só fica healthy depois que sua dependência obrigatória estiver pronta. O Compose deve permitir USE_MOCKS=true para demonstração isolada e USE_MOCKS=false para integração real, sem misturar esses estados silenciosamente.

Mobile

A imagem mobile comprova ambiente reproduzível para instalação, typecheck, testes e export Android. Credenciais Apple/Google, keystores, certificados, provisioning profiles e submissão às lojas nunca entram na imagem nem no repositório. Automação de release para Play Store/App Store pertence a IS-POST-13.1.

Segurança e supply chain

• BuildKit secrets ou secret store do CI para qualquer credencial temporária; nunca ARG persistente para segredo.
• Scan de secrets antes do build e scan de vulnerabilidades da imagem antes de publicar.
• Dependências baixadas somente de registries permitidos; lockfile obrigatório.
• Imagens publicadas registram SHA, alvo, data e versão; SBOM/attestation entram quando a ferramenta gratuita escolhida suportar sem ampliar o escopo.
• Porta, CORS, URLs e modo de mocks são configuração de ambiente, não valores secretos embutidos.

Observabilidade e operação

• Logs em stdout/stderr, sem arquivo local como fonte canônica.
• Healthcheck da API é usado por Compose e plataforma de deploy.
• Smoke identifica ambiente, commit e target sem expor segredo.
• Reinício pode apagar o estado atual em memória; esta limitação deve aparecer no handoff e nos ambientes de teste.

Critérios de aceite

• Web, API e validação mobile constroem em ambiente Linux limpo a partir do lockfile.
• docker compose up sobe web + API e ambos passam health/smoke.
• Mudança em package compartilhado invalida os consumidores corretos.
• Imagens rodam como non-root, não contêm secrets e possuem tamanho/runtime revisados.
• API encerra graciosamente e responde healthcheck.
• Mobile exporta sem credenciais de loja e sem ser tratado como serviço Vercel.
• Rebuild sem mudança relevante reaproveita cache de dependências.
• Runbook documenta limitações do estado em memória e teardown seguro.

Não objetivos

• Kubernetes, service mesh, registry pago ou orquestração multi-região.
• Banco, fila ou storage não aprovados por specs próprias.
• Publicar mobile nas stores.
• Fazer Vercel consumir imagem Docker para o web.
• Declarar Render Free ou qualquer free tier adequado a produção com SLA.

Histórico

• 1.0 — containerização de web/API e toolchain mobile para integração após a direção visual.