# runner ports

Submódulo introduzido na v2.19.0 para inspecionar, liberar e realocar portas alocadas pelo allocator do runner (network.publish_strategy = random | sequential).

Quando o config global tem network: configurado, o runner aloca portas automaticamente da primeira deploy e persiste sticky no state/<app>.yml::network.published_port. Esses comandos manipulam essa alocação sem precisar editar o state file à mão.

# Sintaxe

runner ports list [--json]
runner ports release <app>
runner ports realloc <app>

# `runner ports list`

Lista todas as apps com porta sticky alocada. Útil pra auditar o pool, achar conflitos ou exportar pra ferramentas externas.

# Output humano

APP             VPC_IP       PORT  STRATEGY  ALLOCATED_AT
middleware-241  10.108.0.5   8473  random    2026-05-06T12:30:00Z
sweepapex       10.108.0.5   8501  random    2026-05-06T14:15:00Z
laravel-prod    10.108.0.5   8612  random    2026-05-06T16:00:00Z

Apps sem state.network (legacy v2.18.x ou strategy=Explicit) não aparecem na lista.

# Output JSON

runner ports list --json | jq

{
  "count": 3,
  "ports": [
    {
      "app": "middleware-241",
      "vpc_ip": "10.108.0.5",
      "port": 8473,
      "strategy": "random",
      "allocated_at": "2026-05-06T12:30:00Z"
    },
    {
      "app": "sweepapex",
      "vpc_ip": "10.108.0.5",
      "port": 8501,
      "strategy": "random",
      "allocated_at": "2026-05-06T14:15:00Z"
    }
  ]
}

# `runner ports release `

Limpa todo o bloco state.network da app (libera porta de volta ao pool, sem parar container). A próxima deploy vai realocar do zero.

runner ports release middleware-241
# → Released network state for middleware-241 (port 8473 back to pool).
#   Container continues running. Next deploy will allocate a new port.

Quando usar:

• Migrar app de explicit (port hardcoded em .deploy.yml) pra strategy random
• Liberar uma porta específica reservada por engano
• Antes de mudar network.port_range no config global

Atenção: o container continua rodando na porta antiga até a próxima deploy. Se Traefik externo apontar pra porta antiga, vai funcionar. A próxima deploy é que troca.

# `runner ports realloc `

Limpa apenas state.network.published_port (mantém vpc_ip, strategy, allocated_at). A próxima deploy realoca uma nova porta — útil pra "virar" sticky sem perder o resto do contexto.

runner ports realloc middleware-241
# → Cleared sticky port for middleware-241 — next deploy will re-allocate.
#   Remember to update Traefik!

Quando usar:

• Conflito de porta: outro processo no host pegou a porta sticky → realocar
• Mudança de range no config: porta sticky atual ficou fora do novo range
• Reset cosmético sem mexer em estratégia

Aviso loud: depois do realloc, lembre-se de atualizar a config externa (Traefik, firewall, monitoramento) pra apontar pra nova porta. O runner não tem como atualizar Traefik externo automaticamente.

# Diferença entre release e realloc

# Quando usar este comando

# Setup multi-server com Traefik externo

O caso típico: um servidor com várias apps deployadas numa VPC interna, Traefik rodando em outro host roteando pra 10.108.0.5:8473. O runner ports list --json é o pivô:

# No servidor das apps
runner ports list --json | jq -c '.ports[]' > /tmp/ports.json

# No servidor do Traefik
scp host-apps:/tmp/ports.json .
# ... gerar config dinâmica do Traefik a partir desse JSON ...

Realoca quando precisar de porta nova:

runner ports realloc middleware-241
runner deploy middleware-241    # nova porta sticky
runner ports list               # confirma
# Atualizar Traefik externo manualmente

# Veja Também

• Referencia config.yml — bloco network — schema completo
• runner deploy — flags --port e --no-port
• runner status — campo runtime.network no JSON
• Wizard por perfil — port allocation — fluxo end-to-end