Skip to main content

CLI (infra)

CLI ./infra — entrypoint para runtime local, sandbox y operaciones remotas. ↓ Quick Reference · ⬆ Documentación AITHA

The main entrypoint is ./infra from the repository root.

This CLI manages:

  • Local runtime (start/stop/logs for projects in this repo)
  • Sandbox VM lifecycle (Vagrant)
  • Remote bootstrap + staged deploy (Ansible) with layers: core, system, apps

Start with scenario help:

./infra guide
./infra doctor
./infra help

Mental model​

Remote layers​

  • core: Traefik + private registry
  • system: PostgreSQL + Redis + Zitadel
  • apps: everything else (app-layer projects)

Selectors​

Many commands take a <selector>:

  • a remote layer: core|system|apps|all
  • a project name from ./infra list (example: portal)

Inventory (remote)​

Remote operations use the Ansible inventory at deployment/ansible/inventory.

List targets with stable ordinals:

./infra server list --ordinal

You can refer to a server as:

  • an IP/hostname (example: sd1.example.com)
  • an ordinal number from server list --ordinal (example: 1)

Local repo setup (first time)​

./infra setup init
./infra setup prereqs check
./infra env generate
./infra env check

Local daily use (no remote)​

./infra list
./infra up <project>
./infra logs <project>
./infra status <project>
./infra watchdog check      # detectar contenedores caídos (sin recuperar)
./infra watchdog run        # recuperar contenedores caídos (self-heal)

Watchdog (auto-recovery de contenedores)​

./infra watchdog list                       # proyectos + estado + contenedores esperados
./infra watchdog check [proj...]            # detecta caídos, no toca nada
./infra watchdog run [proj...]              # recupera caídos vía `run.sh up`

Instalación segura (timer deshabilitado): sudo bash deployment/scripts/health/install-watchdog.sh. Ver docs/internal/operations/watchdog.md.

Sandbox VM (Vagrant) end-to-end​

./infra sandbox up
./infra sandbox add
./infra init remote 192.168.56.10 all

Non-destructive VM stop:

./infra sandbox down

Destructive VM rebuild:

./infra sandbox recreate

Fresh remote server (full pack)​

./infra server add <host>
./infra init remote <host> all

Fresh remote server (stop after a layer)​

./infra init remote <host> core
./infra init remote <host> system
./infra init remote <host> apps

init remote always starts from bootstrap and then continues up to the selected layer.

Speed/redo controls:

  • Default behavior: phases completed recently are auto-skipped (checkpoint TTL is 24h).
  • Override: ./infra init remote <host> all --ttl-hours 6
  • Force re-run: ./infra init remote <host> all --force core (or --force bootstrap,core)

Remote updates (after bootstrap)​

./infra remote deploy <host|number> core
./infra remote deploy <host|number> system
./infra remote deploy <host|number> apps
./infra remote deploy <host|number> <project>
./infra release <host|number> <project>

SSH without remembering user/port​

./infra remote ssh <host|number>
./infra remote ssh <host|number> -- -vv

Registry model (remote)​

The private registry is loopback-only on the server. You access it via SSH tunnel:

./infra remote tunnel <host|number> registry
curl -fsS http://127.0.0.1:5000/v2/

See docs/internal/operations/registry.md for publish/inspect/cleanup commands.

Safety notes​

  • clean --data is destructive (wipes volumes).
  • init remote is the recommended staged path for a fresh host.
  • remote deploy assumes the host is already bootstrapped/hardened.

See also:

  • docs/internal/operations/local-and-sandbox.md
  • docs/internal/operations/production-install.md
  • docs/internal/operations/registry.md
  • docs/internal/operations/troubleshooting.md