fn_registry/.claude/rules/deploy.md

Deploy de apps a VPS remotos

Arquitectura

El sistema de deploy usa SSH + systemd + rsync. No Docker, no Kubernetes.

• Conexiones SSH → ~/.ssh/config (alias, IP, user, key). Ya hay funciones CRUD: ssh_config_read, ssh_config_find, ssh_config_parse.
• Config de deploy → apps/deploy_server/operations.db tabla deploy_targets (app, host, remote_dir, build_cmd, port, health_path, env).
• Logs de deploy → misma BD, tabla deploy_logs (app, host, status, trigger, duration_ms, error).

App: deploy_server (apps/deploy_server/)

CLI + servidor HTTP. Binario: deploy_server. Build: CGO_ENABLED=1 go build -o deploy_server .

cd apps/deploy_server

# Gestionar targets
./deploy_server target add --app <app> --host <ssh_alias> --port <N> --health /path --build "comando" [--user deploy] [--env '{"K":"V"}']
./deploy_server target list
./deploy_server target remove <app>

# Setup inicial (primera vez, crea dirs + systemd unit)
./deploy_server setup <app> --host <ssh_alias>

# Deploy continuo (build local → rsync → restart → health check)
./deploy_server deploy <app> [--host <ssh_alias>]

# Estado del servicio remoto
./deploy_server status <app>
./deploy_server status --all

# Servidor webhook (auto-deploy en cada push a Gitea)
./deploy_server serve --port 9090

Funciones del registry involucradas

Función	Qué hace	Purity
rsync_deploy_bash_infra	rsync local→remoto con exclusiones	impure
systemd_generate_unit_go_infra	Genera texto .service	pure
systemd_install_go_infra	Sube unit + daemon-reload + enable + start	impure
systemd_restart_go_infra	Reinicia servicio remoto	impure
systemd_status_go_infra	Estado + logs de servicio remoto	impure
vps_setup_app_go_infra	Crea dirs + usuario en VPS	impure
gitea_create_webhook_bash_infra	Crea webhook push en Gitea	impure
setup_vps_app_go_infra	Pipeline: setup completo primera vez	impure
deploy_app_remote_go_infra	Pipeline: deploy continuo	impure

Tipo: DeployConfig_go_infra — struct con toda la config de deploy.

Workflow para un agente

Cuando el usuario diga "sube esta app a este VPS" o "deploya X en Y":

1. Verificar que el host SSH existe

grep "^Host " ~/.ssh/config
# Si no existe el alias, añadirlo:
# Usar ssh_config_add_entry o editar ~/.ssh/config directamente

2. Verificar conectividad

ssh -o BatchMode=yes -o ConnectTimeout=5 <alias> true

3. Registrar el target en deploy_server

cd apps/deploy_server
# Build deploy_server si no existe el binario
CGO_ENABLED=1 go build -o deploy_server .

./deploy_server target add \
  --app <nombre_app> \
  --host <ssh_alias> \
  --port <puerto> \
  --health <path_o_vacio> \
  --build "CGO_ENABLED=0 GOOS=linux go build -o <binario> ." \
  --user deploy

4. Setup inicial

./deploy_server setup <app> --host <ssh_alias>

Esto crea dirs en /opt/apps/<app>/, sube el código, genera el unit systemd e instala el servicio.

5. Deploys posteriores

./deploy_server deploy <app>

Build local → rsync → restart systemd → health check.

6. Auto-deploy con webhook (opcional)

# Lanzar servidor
./deploy_server serve --port 9090

# Crear webhook en Gitea
source bash/functions/infra/gitea_create_webhook.sh
gitea_create_webhook "<owner>" "<repo>" "http://<ip_deploy_server>:9090/webhook/push" "<secret>"

Requisitos en el VPS

• SSH accesible con key auth (configurado en ~/.ssh/config local)
• El usuario SSH debe tener sudo sin password para: systemctl, mv a /etc/systemd/system/, mkdir en /opt/apps/, useradd, chown
• rsync instalado en el VPS
• Puerto del servicio abierto en el firewall del VPS

Builds por lenguaje

Lenguaje	Build command típico
Go	CGO_ENABLED=0 GOOS=linux go build -o <nombre> .
Go + SQLite	CGO_ENABLED=1 GOOS=linux go build -tags fts5 -o <nombre> .
Python	No build — rsync sube los .py, systemd ejecuta python3 main.py
Bash	No build — rsync sube los .sh, systemd ejecuta bash main.sh

Para Go con CGO (SQLite), el VPS debe tener gcc y libc-dev, o cross-compilar con CGO_ENABLED=0 si la app no usa SQLite.

Exclusiones de rsync

El deploy excluye automáticamente: .git, operations.db*, *.exe, node_modules, .venv, __pycache__, build/, *.db-shm, *.db-wal, registry.db.