Docker Compose

Compose é o caminho mais direto para rodar o Agent num host único — uma VM dedicada, por exemplo. Para orquestradores, veja Kubernetes ou a configuração de produção.

Um compose.yml mínimo

services:
  rootpilot-agent:
    image: <endereço>/rootpilot-agent@sha256:<digest>
    restart: unless-stopped
    stop_grace_period: 150s
    volumes:
      - rootpilot-identity:/identity
    environment:
      RUNNER_TUNNEL_URL: wss://tunnel.rootpilot.sh:8443
      RUNNER_ENROLL_URL: https://app.rootpilot.sh
      RUNNER_ATTESTATION_MODE: bootstrap-token
      RUNNER_BOOTSTRAP_TOKEN: ${RUNNER_BOOTSTRAP_TOKEN}
      RUNNER_IDENTITY_DIR: /identity
      RUNNER_INSTANCE_ID: agent-prod-1
      RUNNER_CONNECTORS: real
      RUNNER_SECRET_STORE_MODE: aws
      NODE_ENV: production

volumes:
  rootpilot-identity:

stop_grace_period maior que RUNNER_DRAIN_TIMEOUT_MS (2 minutos por padrão): senão o SIGKILL chega no meio da drenagem.

A identidade precisa de um volume gravável

É o que faz docker compose pull && up -d não custar um bootstrap token novo. Sem ele, a identidade morre com o container e o token anterior já foi gasto — ele é de uso único.

Prefira um volume nomeado, como no exemplo acima. A imagem já traz /identity pertencendo ao uid 1000 (ela roda como não-root), e um volume nomeado herda essa posse ao ser criado — ou seja, funciona sem você fazer nada.

Um bind mount (./identity:/identity) não herda nada: ali a posse é a do diretório no host, e ele precisa ser do uid 1000. Nunca monte com :ro.

Se o diretório não for gravável, o boot não falha — o Agent avisa e segue, e você só descobre no deploy seguinte:

could not persist identity — next boot will re-enroll from scratch

Um volume de identidade por Agent

O RUNNER_IDENTITY_DIR basta sozinho: o Agent grava ali um id de dono na primeira vez que usa o diretório, e é ele — não o RUNNER_INSTANCE_ID — que faz a identidade ser reconhecida depois de o container ser recriado.

O que não pode é dois Agents no mesmo volume: cada boot sobrescreveria a identidade do outro e os dois voltariam a gastar bootstrap token. Um volume por Agent.

O RUNNER_INSTANCE_ID acima segue no compose porque identifica a instância nos logs e no Fleet — não porque a persistência precise dele.

Os certificados, se você usa certificado provisionado

volumes:
  - ./certs:/certs:ro

O diretório deve conter runner.crt, runner.key e ca.pem. O entrypoint os lê e exporta como RUNNER_CERT_PEM, RUNNER_KEY_PEM e RUNNER_CA_PEM — o Agent lê PEM inline, não caminho, e montar o diretório evita o pesadelo de PEM multilinha dentro de env_file.

Esse caminho ignora enrollment e identidade persistida: os dois blocos acima deixam de valer, e o certificado não se renova. Ver Identidade e enrollment.

Se o Agent roda em EC2 e usa a cadeia de credenciais

Com RUNNER_AWS_CRED_MODE=chain, a cadeia padrão do SDK resolve pelo instance profile sem nenhum volume extra. Se em vez disso você usa um perfil local por arquivo, monte-o:

volumes:
  - ${HOME}/.aws:/home/node/.aws:ro

Sem esse volume o container não enxerga o perfil, e a cadeia falha sem dizer que é isso — o clássico “funciona no meu terminal e não no container”.

Segredo ausente não é erro: é um serviço que some

Se uma credencial obrigatória de um connector não chegar ao container, o Agent sobe normalmente, tira aquele serviço do conjunto que ele serve, e o único sinal é uma linha connector not served: required secret absent no log de boot.

Não é falha de instalação — é o comportamento correto para quem conectou só parte das fontes. Mas se você esperava aquele serviço, é aí que aparece. O Fleet do control-plane mostra o mesmo estado.