13 · Containers, implantação e segredos

Regras para todo deploy/<app>/Dockerfile:

Site estático: nginx com tag completa, HTML + CSS, variáveis por envsubst no entrypoint, sem JavaScript se o produto assim decidir.

Dois caminhos, ambos documentados em docs/guias/desenvolvimento-local.md:

Regras do Compose:

• descartável: sem volume nomeado; eng/dev-db.sh reset zera;
• derrubar e zerar alcançam todos os perfis: o down do eng/dev-db.sh é docker compose --profile '*' down --volumes --remove-orphans. Com só os perfis padrão, um container parado de outro perfil sobrevive preso à rede apagada, e o up seguinte falha com network … not found;
• credenciais óbvias e falsas (<produto>/<produto>, admin/admin, dev-secret-<client>), que só existem aqui;
• mesmas imagens e tags do deploy.yml e dos testes (conferido pela CI);
• portas locais fixas e documentadas na ficha (uma por aplicação, mais a de métricas publicada só no local);
• observabilidade local num perfil (--profile observability), que não sobe por padrão.

Cada aplicação tem deploy/<app>/ e o Kamal roda de dentro dessa pasta. Há um ambiente implantado só, a produção (DEPLOYMENT_ENVIRONMENT=production); o outro é o local, no Compose. Um ambiente implantado de desenvolvimento ainda não existe na arquitetura (12).

deploy/<app>/
├── Dockerfile
├── config/deploy.yml     # serviço, host, proxy, env, accessories
└── .kamal/secrets        # SÓ referências ao Bitwarden

O esqueleto, pronto para copiar, está no deploy/README.md do modelo. Elementos fixos de todo deploy.yml; os valores da plataforma vêm do contrato:

O contrato da plataforma

O que o toolbox garante a toda stack, para ela preencher o deploy.yml sem ler o toolbox. Cada valor tem a fonte lá. Mudar um deles muda todas as stacks: o toolbox não o faz sem uma versão nova da arquitetura que traga o valor novo, e o "Para as stacks" do CHANGELOG.md diz a troca.

Regras dos accessories

Regras:

• um projeto no Bitwarden para o produto, lido por todas as aplicações, e todo segredo com o prefixo do produto (ATENDIMENTO_). O que as aplicações compartilham, como a senha de um armazenamento, é um nome só; o que cada uma tem o seu leva o nome dela (ATENDIMENTO_CONSOLE_OIDC_CLIENT_SECRET);
• o .kamal/secrets tem só referências; todo $(...) abre e fecha na mesma linha (toolbox ADR-0031);
• segredos de terceiros usados por scripts (ex.: credenciais do IdP Google) também vêm do Bitwarden, exportados pelo mantenedor na hora;
• o agente escreve as referências e os nomes, nunca valores; nos documentos, <VALOR>.

O mínimo no Bitwarden: três tipos de linha

O Kamal roda cada $(kamal secrets …) dentro do próprio processo, sem shell: não há || echo padrão, e um nome que falta no Bitwarden para o deploy inteiro. O .kamal/secrets é lido como um .env, que troca ${NOME} pelo valor de uma linha anterior, mas não conhece ${NOME:-padrão}. Com isso, cada variável é de um de três tipos:

A linha de padrões usa o Ruby que o Kamal já exige:

SECRETS=$(ruby -rjson -rshellwords -e 'defaults = {"<PREFIXO>_NATS_USER" => "<padrão>"}; print JSON.dump(defaults.merge(JSON.parse(ARGV[0]))).shellescape' $SECRETS)

• Todo valor que se deduz de partes fixas e de outros segredos é composto, e não se cadastra: a URI do banco se monta com a senha;
• só um nome de usuário pode ter padrão, porque um padrão está no repositório;
• uma senha que entra numa URI é gerada com openssl rand -hex: um @, : ou / quebraria a URI composta;
• o eng/deploy-secrets.sh confere tudo isso, e que cada nome do deploy.yml tem a sua linha, na CI.

O guia de implantação da stack cataloga todas as variáveis, em quatro tabelas: obrigatórias (o nome completo no Bitwarden, pronto para copiar, quem usa e como gerar), opcionais (o padrão e quando trocar), compostas (como se montam) e fixas (no deploy.yml ou na imagem). Para conferir o que o Kamal monta sem expor valores: kamal secrets print | cut -d= -f1, de dentro de deploy/<app>/.

Política de domínios do toolbox, aplicada a cada aplicação pela ORG-0017:

Aplicações para públicos diferentes ficam em domínios registráveis diferentes: nenhum cookie de sessão é compartilhado entre elas por construção.

Checklist do guia docs/guias/implantacao.md, que o mantenedor marca. A ordem importa: cada passo depende do anterior.

• Ferramentas e acesso: Kamal e bws nas versões da ficha; BWS_ACCESS_TOKEN e BWS_PROJECT_ID do projeto do produto exportados, sem eco;
• DNS de cada endereço apontado para a VPS;
• Identidade, antes de qualquer deploy: o realm existe no Keycloak real; provision.sh rodado; o segredo de cada client no Bitwarden. Sem ele, o kamal deploy para com Could not find secret;
• Os demais segredos obrigatórios no projeto, conferidos pelos nomes (kamal secrets print | cut -d= -f1);
• A VPS: o kernel e a CPU que as imagens dos armazenamentos exigem, como o guia confere;
• Os accessories da dona do schema (kamal accessory boot all) e os preparos de uma vez só que o guia lista;
• O deploy da dona do schema, depois o das demais; /up respondendo em cada uma;
• O toolbox: o job_name de cada aplicação no Prometheus e o painel, com os blocos prontos do 14; os traces conferidos no Tempo;
• login com um usuário de cada perfil; logs no Grafana;
• o primeiro backup agora, sem esperar a agenda, e a restauração testada localmente com ele.