specsfy-specialist-deploy

Deploy

Quando usar

Acionar quando a pessoa pedir release ou deploy de uma aplicação em servidor.
Acionar para preparar um servidor que receberá stacks Docker Swarm via Ansible.
Acionar quando a pessoa pedir para cadastrar, adicionar, substituir ou conferir um servidor do ambiente.
Não executar push, provisionamento ou mudança remota sem alvo e autorização explícitos.

Fluxo

Apresente o plano, informe o progresso por etapa e encerre com arquivos alterados, validações e pendências. Para texto público, siga o Contrato Editorial Compartilhado aplicável ao projeto consumidor.

Confirmar a raiz do sistema do usuário e acionar $specsfy-specialist-versioning para ler ou preparar SEMVER.
Inspecionar Dockerfile, Compose, stack e ansible/ existentes. Comparar PHP, extensões, dependências, assets, entrypoint, usuário interno, portas, healthcheck e comando do Octane com a aplicação atual. Preservar trechos personalizados e apresentar o diff antes de substituir um arquivo sem marcações gerenciadas.
Executar o gerador somente na primeira preparação, quando todos os destinos estiverem ausentes:
```
node scripts/scaffold.mjs --project <raiz> --image <registry>/<aplicacao>
```
O padrão inclui Cloudflare Tunnel na stack. Se a pessoa pedir outro proxy, gerar sem cloudflared com --proxy external e configurar a alternativa solicitada em etapa própria.
Acionar $specsfy-specialist-debian-server para levantar as máquinas uma por rodada. Registrar hostname, endereço, porta SSH, usuário de conexão e papel manager ou worker em ansible/inventory.yml, preservando os hosts já cadastrados. Quando chegar uma máquina nova, adicionar somente esse host.
Testar todos os hosts declarados antes de qualquer alteração remota. A skill executa o utilitário, mas também mostra a forma curta para uso no Herdr:
```
./deploy check-hosts
```
Localizar apenas chaves públicas ~/.ssh/*.pub na máquina controladora e adicioná-las ao authorized_keys do usuário deploy. Nunca ler, copiar ou transmitir uma chave privada. Manter acessos remotos já cadastrados.
Perguntar quais senhas, tokens, chaves e keys a aplicação consome e registrar os nomes em ansible/vault-fields.txt. Não pedir os valores na conversa. O utilitário solicita cada valor com entrada oculta e grava o YAML criptografado:
```
./deploy secrets
```
A repetição mantém os campos existentes e pergunta somente os ausentes.

No padrão Cloudflare Tunnel, incluir vault_cloudflare_tunnel_token. O serviço lê o token pelo arquivo /run/secrets/cloudflare_tunnel_token.
Gerar a referência da imagem com docker-tag. Recusar qualquer tag Docker diferente do valor presente em SEMVER.
Acionar $specsfy-specialist-debian-server e $specsfy-specialist-docker para definir o estado do host e do Docker Engine.
Acionar $specsfy-specialist-ansible para criar ou revisar roles idempotentes que criam o usuário deploy, instalam Docker Engine, configuram daemon, firewall, permissões e diretórios da aplicação.
Acionar $specsfy-specialist-docker-swarm para definir managers, workers, redes e stacks. O playbook executa docker swarm init somente quando o manager ainda não participa de um swarm e usa tokens protegidos para joins.
Validar Ansible em syntax check, lint, check mode e duas execuções num alvo descartável. Validar a stack com docker stack config.
Com autorização para o alvo informado, usar ./deploy run --non-interactive quando o agente executar o deploy. A senha vem de uma fonte externa já configurada. Na ausência dessa fonte, orientar a pessoa a executar ./deploy configure-vault no próprio terminal; não pedir, ler ou imprimir a senha na conversa. Preservar ./deploy run como caminho manual. Aplicar o playbook, publicar a imagem versionada e executar docker stack deploy pelo manager.
Conferir réplicas, healthchecks, logs, versão e digest. Guardar o comando de rollback para a versão anterior.

Padrões

Ler references/vault.md antes de configurar a senha, migrar scripts existentes ou executar pelo agente. A fonte explícita tem precedência sobre ambiente e ansible.cfg; o cadastro local é a alternativa quando nenhuma fonte nativa existe. Falha de uma fonte encerra a execução.
Não executar configure-vault pela IA para preencher a senha. Esse comando pertence à preparação humana, em terminal com entrada oculta.
Atualizar projetos existentes por diff, preservando personalizações. O scaffold continua recusando sobrescrita e a atualização da skill não migra automaticamente ./deploy ou ansible/.
SEMVER na raiz do sistema do usuário governa imagem, manifesto, tag Git e release.
Gerar compose.yaml para desenvolvimento e stack.yaml para produção. Toda produção usa a stack pelo Docker Swarm; não use Compose como runtime de produção.
Em Laravel, exigir laravel/octane e Open Swoole. A imagem instala openswoole; Compose e stack executam Octane com --server=swoole.
Sugerir Cloudflare Tunnel como entrada pública padrão. Executar cloudflared como serviço da stack, ligado à mesma rede overlay da aplicação e sem porta pública no serviço Laravel. O hostname do túnel aponta para http://app:8000.
Trocar o padrão somente quando a pessoa pedir outro proxy. Nesse caso, não gerar o serviço cloudflared nem o secret do token.
Ansible configura o servidor e o estado do Swarm. Não deixe uma sequência manual de comandos SSH como procedimento principal.
Criar o usuário de serviço deploy, adicionar somente esse usuário ao grupo docker e atribuir a ele os diretórios da aplicação. O grupo concede acesso administrativo amplo ao host e não deve incluir contas sem essa função.
Manter ansible/inventory.yml como mapa dos servidores conhecidos. Uma inclusão preserva os hosts atuais, testa a nova conexão e só então configura o node e seu papel no Swarm.
Mostrar ./deploy check-hosts, ./deploy secrets, ./deploy sync-keys ou ./deploy run quando a pessoa precisar copiar uma ação para outro painel do Herdr. A skill executa esses utilitários sem exigir memorização.
Em nova chamada, ler novamente a aplicação e reconciliar apenas o que mudou. O gerador serve ao primeiro bootstrap e não deve sobrescrever arquivos existentes para simular atualização.
Use módulos idempotentes e community.docker; comandos necessários para iniciar ou integrar o swarm precisam de condições baseadas no estado atual.
Mantenha managers em número ímpar e restrinja as portas do Swarm aos nodes autorizados.
Publique uma imagem uma vez e promova o mesmo digest entre ambientes.
Senhas, tokens e chaves entram em um Ansible Vault criado por prompt seguro. O Ansible transforma os valores descriptografados em Docker Secrets com no_log: true; a stack guarda apenas nomes e mounts externos.

Antipadrões

Usar latest ou outra tag que não reproduza SEMVER.
Executar docker swarm init em toda rodada do playbook.
Expor token de join em log, variável aberta ou arquivo commitado.
Guardar senha, token ou chave no stack.yaml, em variável aberta ou na imagem.
Passar o token do Cloudflare Tunnel por argumento, variável aberta ou arquivo versionado.
Conceder sudo irrestrito ao usuário deploy sem necessidade confirmada.
Fazer build no servidor ou recompilar uma imagem para cada ambiente.
Considerar o deploy concluído apenas porque o comando retornou código zero.

Validação

Comprovar o prompt manual, arquivo externo, script de cofre e configuração nativa em um alvo descartável. Sem senha válida, a execução deve parar antes de conectar aos hosts. Conferir permissões 700 e 600, confirmação de substituição e ausência de valores secretos na saída do configurador.
Executar current, docker-tag e verify-docker-tag pela skill de versionamento.
Confirmar que deploy existe, pertence ao grupo docker, acessa o daemon e é owner dos diretórios da aplicação.
Confirmar Docker Engine ativo, manager alcançável e swarm em estado active.
Executar o playbook duas vezes; a segunda rodada deve terminar sem mudanças.
Comparar a imagem de cada serviço com SEMVER e com o digest publicado.
Observar a convergência e ensaiar rollback em ambiente compatível.

Skills relacionadas

$specsfy-specialist-versioning governa a versão do sistema do usuário.
$specsfy-specialist-debian-server define o estado base do host.
$specsfy-specialist-docker prepara e publica a imagem.
$specsfy-specialist-ansible automatiza o servidor e o cluster.
$specsfy-specialist-docker-swarm governa serviços, rollout e rollback.
$specsfy-specialist-delivery-engineering governa pipeline e promoção entre ambientes quando esses componentes fizerem parte da entrega.

Leia references/standards.md antes de criar ou alterar o playbook de provisionamento e deploy.