Operação de deploy no Specsfy: servidores, conexões e chaves

A specsfy-specialist-deploy prepara os arquivos do projeto e mantém a lista de máquinas que receberão a aplicação. Este capítulo detalha essa camada operacional: onde cada arquivo fica, como uma máquina entra no ambiente, o que o teste de conexão comprova e quais comandos curtos você pode copiar no Herdr.

Onde a automação fica no seu projeto

A skill trabalha a partir da raiz que você confirmou. Os arquivos permanecem junto do sistema para que o Git mostre quando a infraestrutura muda com o código:

1
meu-projeto/
2
├── deploy
3
├── SEMVER
4
├── Dockerfile
5
├── compose.yaml
6
├── stack.yaml
7
├── docker/
8
│   └── entrypoint.sh
9
└── ansible/
10
    ├── inventory.yml
11
    ├── inventory.example.yml
12
    ├── check-hosts.py
13
    ├── create-vault.sh
14
    ├── deploy.yml
15
    ├── keys.yml
16
    ├── sync-keys.yml
17
    ├── secrets.yml
18
    ├── vault-fields.txt
19
    ├── group_vars/
20
    │   ├── all.yml
21
    │   └── all/
22
    │       └── vault.yml
23
    └── templates/
24
        └── stack.yaml.j2

No modo padrão, vault-fields.txt inclui vault_cloudflare_tunnel_token. Você informa esse valor pelo prompt oculto de ./deploy secrets, junto dos demais secrets ainda ausentes. O template da stack monta o Docker Secret no serviço cloudflared, que compartilha a rede overlay com app.

O arquivo deploy oferece nomes curtos para ações que você pode copiar em outro painel do Herdr. Você não precisa iniciar o fluxo por esses comandos. Um pedido como “faça o deploy desta aplicação” continua sendo a entrada normal, e a IA executa as ferramentas conforme o estado encontrado.

O que muda quando você pede outro deploy

Na primeira preparação, o gerador cria a base quando nenhum dos destinos existe. Nas chamadas seguintes, a IA não executa o gerador sobre os mesmos arquivos. Ela lê a aplicação outra vez, compara a infraestrutura atual com as necessidades do código e modifica somente o que precisa acompanhar a entrega.

O Dockerfile recebe uma revisão própria. Em Laravel, a skill confere a versão do PHP, as extensões exigidas pelo Composer, o pacote laravel/octane, a extensão openswoole, o build dos assets, o entrypoint, as permissões, a porta, o healthcheck e o comando octane:start --server=swoole. Uma dependência nova que exija outra extensão PHP deve aparecer nessa análise antes do build.

O mesmo exame alcança compose.yaml, stack.yaml, docker/ e ansible/. Quando um arquivo possui personalizações do projeto, a skill preserva esses trechos e apresenta a comparação dos arquivos alterados antes de substituir uma estrutura sem marcações gerenciadas. Repetir o pedido não significa gerar tudo novamente. Significa reconciliar o estado existente com a aplicação que será publicada.

Essa reconciliação também confere o ingresso. Sem uma escolha diferente, a IA mantém Cloudflare Tunnel como serviço da stack. Quando você pedir outro proxy, ela remove ou deixa de gerar os componentes do túnel e prepara a alternativa solicitada sem misturar tokens entre os dois caminhos.

Como os servidores entram no inventário

Antes da primeira conexão, a orquestradora aciona o especialista de Debian e pergunta quais máquinas fazem parte do ambiente. A conversa trata um servidor por rodada. Para cada máquina, você confirma:

Essas respostas formam ansible/inventory.yml. O arquivo de exemplo ensina o formato, mas nunca substitui o inventário real durante uma conexão.

Quando você disser “adicione um novo servidor”, a skill lê os hosts atuais e pergunta somente pelos dados da nova máquina. Depois, ela acrescenta o host ao grupo escolhido, testa o SSH, sincroniza as chaves públicas, prepara o usuário deploy, instala o Docker e integra o node ao Swarm. Os servidores anteriores permanecem no arquivo e não são renomeados ou removidos nessa operação.

A conta do servidor e a conta do container

O host e o container usam nomes diferentes porque cumprem funções diferentes. No Debian, deploy é a conta operacional que recebe as chaves SSH, pertence ao grupo docker e administra os diretórios sob /opt/apps. Dentro da imagem, app continua sendo a conta sem privilégios que executa o Laravel Octane.

1
máquina local ──SSH──> deploy@servidor ──Docker──> container: usuário app

O acesso por senha da conta deploy permanece desabilitado. O grupo docker concede controle amplo sobre o host, por isso a automação não adiciona outras contas a esse grupo sem uma necessidade confirmada.

Teste das conexões

Antes de alterar qualquer servidor, a skill executa o teste abaixo. Assim, um host inacessível aparece na tabela antes que o playbook modifique outra máquina:

1
./deploy check-hosts

O comando lê ansible/inventory.yml, chama o módulo ping do Ansible e mostra uma linha por máquina:

1
SERVIDOR  ENDEREÇO       PORTA  USUÁRIO  PAPEL    ESTADO
2
--------  -------------  -----  -------  -------  ----------
3
app01     203.0.113.10   22     root     manager  conectado
4
app02     203.0.113.11   22     deploy   worker   conectado

O estado conectado confirma que o Ansible conseguiu autenticar e executar o módulo remoto. Ele não afirma que o Docker ou a aplicação estejam saudáveis. Se qualquer host estiver inacessível, o comando termina com erro e o deploy para antes da primeira escrita remota.

Sincronização das chaves públicas

A automação procura arquivos com o padrão ~/.ssh/*.pub na máquina que está executando o agente. Somente o conteúdo das chaves públicas entra no authorized_keys de deploy em cada servidor cadastrado. Arquivos privados, como id_ed25519 ou id_rsa sem o sufixo .pub, não são abertos nem enviados.

Quando você quiser executar apenas essa etapa em um painel do Herdr, use:

1
./deploy sync-keys

A operação primeiro executa check-hosts. Depois, mantém as chaves já presentes e inclui somente as ausentes. Ela não usa sincronização exclusiva e, portanto, não remove o acesso de outra máquina administrativa.

Comandos curtos para o Herdr

O inventário padrão é ansible/inventory.yml. Para conferir outro arquivo sem alterar o projeto, defina ANSIBLE_INVENTORY somente para aquela execução. Estes exemplos cobrem as ações disponíveis:

1
./deploy check-hosts
2

3
ANSIBLE_INVENTORY=ansible/inventory.staging.yml ./deploy check-hosts
4

5
./deploy secrets
6

7
./deploy sync-keys
8

9
./deploy run

check-hosts não recebe senhas como argumentos. secrets abre prompts ocultos e não aceita valores pela linha de comando. sync-keys recusa continuar quando não encontra uma chave pública local. run testa as conexões antes do playbook e solicita a senha do Vault no próprio terminal quando ela for necessária.

Volte ao capítulo Como funciona o Deploy da aplicação para acompanhar build, publicação, rollout, migrations, rollback e conferência da versão ativa.