docs: regla deploy, template project, gitignore projects/vaults

Añade regla deploy.md con arquitectura SSH+systemd+rsync, workflow completo para agentes, y referencia a todas las funciones involucradas. Actualiza INDEX.md con la nueva regla. Añade template project.md para fn add -k project. Gitignore projects/*/ y vaults/*/ (contenido local, solo manifests se versionan).
2026-04-12 17:30:01 +02:00
parent 6b8bcd0939
commit cc922f04ea
4 changed files with 152 additions and 0 deletions
@@ -17,3 +17,4 @@ Reglas operativas del proyecto. Cada archivo es una regla independiente.
 | 11 | [sources.md](sources.md) | Extraccion de funciones desde repos externos |
 | 12 | [notebook_collaboration.md](notebook_collaboration.md) | Colaboración en notebooks Jupyter via funciones del registry |
 | 13 | [frontend_theming.md](frontend_theming.md) | Componentes propios y sistema de temas en frontends |
+| 14 | [deploy.md](deploy.md) | Deploy de apps a VPS remotos via SSH + systemd + rsync |
@@ -0,0 +1,134 @@
+## 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 .`
+
+```bash
+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
+
+```bash
+grep "^Host " ~/.ssh/config
+# Si no existe el alias, añadirlo:
+# Usar ssh_config_add_entry o editar ~/.ssh/config directamente
+```
+
+#### 2. Verificar conectividad
+
+```bash
+ssh -o BatchMode=yes -o ConnectTimeout=5 <alias> true
+```
+
+#### 3. Registrar el target en deploy_server
+
+```bash
+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
+
+```bash
+./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
+
+```bash
+./deploy_server deploy <app>
+```
+
+Build local → rsync → restart systemd → health check.
+
+#### 6. Auto-deploy con webhook (opcional)
+
+```bash
+# 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`.
@@ -37,6 +37,13 @@ python/.venv/
 apps/*/
 analysis/*/

+# Projects (each is its own git repo, only project.md templates are versioned)
+projects/*/
+
+# Vaults — data stores (symlinks, dirs, files); only vault.yaml manifest is versioned
+vaults/*/
+!vaults/vault.yaml
+
 # Node / pnpm
 **/node_modules/

@@ -0,0 +1,10 @@
+---
+name: my_project
+description: "Descripcion breve del proyecto."
+tags: []
+repo_url: ""
+---
+
+## Notas
+
+Notas adicionales sobre el proyecto.