Instalação

O HeroCtl roda em qualquer servidor Linux com Docker. O binário é único e contém os três modos de execução: servidor, agente e CLI. Você decide o papel da máquina via flag, não via pacote.

Pré-requisitos

Antes de instalar, confirme o ambiente. A lista é curta e firme.

Nota: o Docker precisa estar em execução antes do install. Verifique com docker info. Se a saída der erro de socket, ajuste permissões antes de prosseguir.

Comando de instalação

Um comando entrega o binário, configura o serviço e gera o arquivo de configuração padrão.

curl -sSL https://get.heroctl.com/install.sh | sh

O script executa quatro passos, em ordem:

1. Baixa o binário mais recente para /usr/local/bin/heroctl.
2. Cria o usuário de sistema heroctl e os diretórios /etc/heroctl/ e /var/lib/heroctl/.
3. Registra um serviço systemd (heroctl.service) sem habilitar o start automático.
4. Gera /etc/heroctl/server.yaml com defaults seguros (bind em 127.0.0.1, sem TLS).

Sem surpresas. O script não toca em nada fora desses caminhos e não inicia processos.

Verificação pós-instalação

Após o script terminar, dois comandos confirmam que o binário responde.

heroctl version
# heroctl 1.0.0 (commit abc123, build 2026-04-20)

heroctl status
# binary: ok
# config: /etc/heroctl/server.yaml
# docker: connected (24.0.7)
# service: inactive (não iniciado)

Se docker: connected aparecer com erro, o binário não consegue falar com o socket. Adicione o usuário heroctl ao grupo docker e reinicie o serviço.

sudo usermod -aG docker heroctl
sudo systemctl restart heroctl

Os três modos do binário

O mesmo executável muda de papel pela flag inicial. Não existe pacote separado.

Em produção, 3 nós rodam servidor + agente. Workers extras rodam só agente. O modo CLI é stateless e pode rodar do laptop do operador.

Bootstrap inicial

O primeiro nó precisa inicializar o estado do cluster. Esse passo é único e só acontece uma vez na vida da instalação.

sudo heroctl server --bootstrap --advertise 10.0.0.1

A flag --advertise é o IP que outros nós vão usar para conectar. Em ambiente de teste, pode ser 127.0.0.1. Em produção, é o IP privado da máquina.

Após o bootstrap, o serviço fica em execução em segundo plano. Confirme com:

heroctl cluster status
# nodes:    1
# leader:   self
# applied:  42
# health:   ok

Para subir nós adicionais e formar um cluster real, siga para Subir cluster de 3 nós.

Problemas comuns

Porta 8080 em uso

O HeroCtl reserva 8080 para a API HTTP. Se outro processo já ocupa, edite /etc/heroctl/server.yaml antes do bootstrap.

api:
  bind: 0.0.0.0
  port: 9080

Reinicie o serviço com sudo systemctl restart heroctl.

Permissão negada no Docker

A mensagem permission denied while trying to connect to the Docker daemon aparece quando o usuário heroctl não está no grupo docker. Resolva com o usermod mostrado acima e reinicie o serviço.

Firewall bloqueando o cluster

Em provedores como DigitalOcean ou Hetzner, o firewall externo bloqueia 8080–8082 por padrão. Libere as três portas entre os IPs dos nós antes de tentar formar cluster. Para acesso externo à API, mantenha 8080 aberto apenas para IPs administrativos.

Binário não encontrado após install

O script instala em /usr/local/bin/. Se o PATH da sessão atual não inclui esse diretório, abra um novo shell ou rode hash -r.

Desinstalação

Reverter é simétrico. Remove serviço, binário e dados, nessa ordem.

sudo systemctl stop heroctl && sudo systemctl disable heroctl
sudo rm /etc/systemd/system/heroctl.service
sudo rm /usr/local/bin/heroctl
sudo rm -rf /etc/heroctl /var/lib/heroctl
sudo userdel heroctl

Atenção: o diretório /var/lib/heroctl/ contém o estado do cluster. Apagar significa perder o histórico de deploys e definições de jobs. Faça snapshot antes se houver chance de reinstalar.

Próximo passo: formar um cluster de 3 nós.