Instalación

HeroCtl corre en cualquier servidor Linux con Docker. El binario es único y contiene los tres modos de ejecución: servidor, agente y CLI. Decides el rol de la máquina vía flag, no vía paquete.

Prerrequisitos

Antes de instalar, confirma el entorno. La lista es corta y firme.

Nota: Docker debe estar en ejecución antes del install. Verifica con docker info. Si la salida da error de socket, ajusta permisos antes de continuar.

Comando de instalación

Un comando entrega el binario, configura el servicio y genera el archivo de configuración por defecto.

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

El script ejecuta cuatro pasos, en orden:

1. Descarga el binario más reciente a /usr/local/bin/heroctl.
2. Crea el usuario de sistema heroctl y los directorios /etc/heroctl/ y /var/lib/heroctl/.
3. Registra un servicio systemd (heroctl.service) sin habilitar el arranque automático.
4. Genera /etc/heroctl/server.yaml con defaults seguros (bind en 127.0.0.1, sin TLS).

Sin sorpresas. El script no toca nada fuera de esas rutas y no inicia procesos.

Verificación post-instalación

Tras terminar el script, dos comandos confirman que el binario 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)

Si docker: connected aparece con error, el binario no logra hablar con el socket. Agrega el usuario heroctl al grupo docker y reinicia el servicio.

sudo usermod -aG docker heroctl
sudo systemctl restart heroctl

Los tres modos del binario

El mismo ejecutable cambia de rol por la flag inicial. No existe paquete separado.

En producción, 3 nodos corren servidor + agente. Workers extras corren solo agente. El modo CLI es stateless y puede correr desde el laptop del operador.

Bootstrap inicial

El primer nodo necesita inicializar el estado del cluster. Ese paso es único y solo ocurre una vez en la vida de la instalación.

sudo heroctl server --bootstrap --advertise 10.0.0.1

La flag --advertise es la IP que otros nodos usarán para conectar. En entorno de prueba, puede ser 127.0.0.1. En producción, es la IP privada de la máquina.

Tras el bootstrap, el servicio queda en ejecución en segundo plano. Confirma con:

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

Para levantar nodos adicionales y formar un cluster real, sigue a Levantar cluster de 3 nodos.

Problemas comunes

Puerto 8080 en uso

HeroCtl reserva 8080 para la API HTTP. Si otro proceso ya lo ocupa, edita /etc/heroctl/server.yaml antes del bootstrap.

api:
  bind: 0.0.0.0
  port: 9080

Reinicia el servicio con sudo systemctl restart heroctl.

Permiso denegado en Docker

El mensaje permission denied while trying to connect to the Docker daemon aparece cuando el usuario heroctl no está en el grupo docker. Resuelve con el usermod mostrado arriba y reinicia el servicio.

Firewall bloqueando el cluster

En proveedores como DigitalOcean o Hetzner, el firewall externo bloquea 8080–8082 por defecto. Libera los tres puertos entre las IPs de los nodos antes de intentar formar cluster. Para acceso externo a la API, mantén 8080 abierto solo para IPs administrativas.

Binario no encontrado tras install

El script instala en /usr/local/bin/. Si el PATH de la sesión actual no incluye ese directorio, abre un nuevo shell o ejecuta hash -r.

Desinstalación

Revertir es simétrico. Remueve servicio, binario y datos, en ese orden.

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

Atención: el directorio /var/lib/heroctl/ contiene el estado del cluster. Borrarlo significa perder el historial de deploys y definiciones de jobs. Haz snapshot antes si hay chance de reinstalar.

Próximo paso: formar un cluster de 3 nodos.