feature/generador-instaladores-linux-windows

2026-07-30 07:34:17 -06:00
parent cafe3f1b87
commit c3f1d70e23
34 changed files with 3498 additions and 252 deletions
--- a/BUILD.md
+++ b/BUILD.md
@@ -13,11 +13,12 @@ Qt instaladas en el equipo destino. Todo se embebe dentro del binario en tiempo
 Orquestador único. **Se ejecuta desde WSL** (bash). Genera Windows + Linux + los paquetes.

 ```bash
-./build-all.sh                 # Windows + Linux + dist/release/*.tar.gz y *.zip
+./build-all.sh                 # Windows + Linux + paquetes versionados en dist/release/
 ./build-all.sh --linux-only    # solo Linux (Docker)
 ./build-all.sh --windows-only  # solo Windows (PowerShell + build.ps1)
 ./build-all.sh --no-package    # compila sin generar .tar.gz/.zip
 ./build-all.sh --clean         # rebuild desde cero (borra venvs, bundled, dist)
+./build-all.sh --publish       # además publica en Gitea (ver §5; requiere GITEA_TOKEN)
 ./build-all.sh --help
 ```

@@ -72,21 +73,85 @@ Los binarios quedan en `packaging/bundled/{linux,windows}/` (git-ignored, se gen
 bash packaging/scripts/package-release.sh
 ```

+La versión sale de `app/__init__.py` (fuente única) y va en el nombre de cada paquete.
+El script aborta si la versión no es puntos-y-números: el PANEL las compara como tuplas
+de enteros y otro formato rompería en silencio la detección de "hay versión nueva".
+
 Genera en `dist/release/`:

 | Archivo | Contenido |
 |---|---|
-| `CloudRestoreAS-linux.tar.gz` | `CloudRestoreAS/` → binario + `install.sh` + `packaging/linux/cloudrestoreas.service` + `LEEME.txt` |
-| `CloudRestoreAS-win.zip` | `CloudRestoreAS/` → `CloudRestoreAS.exe` + `install.ps1` + `LEEME.txt` |
+| `CloudRestoreAS-<version>-linux-<arch>.tar.gz` | `CloudRestoreAS/` → binario + `install.sh` + `packaging/linux/cloudrestoreas.service` + `LEEME.txt` |
+| `CloudRestoreAS-<version>-win-<arch>.zip` | `CloudRestoreAS/` → `CloudRestoreAS.exe` + `install.ps1` + `LEEME.txt` |
+| `SHA256SUMS` | Checksums de los dos paquetes |
+| `release.json` | Manifiesto: versión, fecha, artefactos (platform/arch/tamaño/sha256) y deps embebidas. Es lo que lee `publish-release.sh` para saber qué subir |
+
+Además deja copias crudas sin versión (`CloudRestoreAS.exe`, `CloudRestoreAS-linux`) para
+la verificación de autocontención de la §9. Esas **no** se publican.
+
+`arch` se declara con `CLOUDRESTORE_TARGET_ARCH` (default `x86_64`): el `.exe` lo compila
+el host Windows y desde WSL no hay forma de inferir su arquitectura.

 ---

-## 5. Instalación / despliegue
+## 5. Publicación a Gitea — `publish-release.sh`
+
+Los binarios viven en el **registro de paquetes genéricos de Gitea**, que es la fuente de
+verdad que consume el PANEL. Gitea calcula y expone el `sha256` de cada archivo, así que
+no hace falta mantener un manifiesto de integridad propio: el PANEL verifica sus descargas
+contra ese hash.
+
+```bash
+# Requiere un PAT de Gitea con scope write:package
+export GITEA_TOKEN=xxxxxxxx
+
+bash packaging/scripts/publish-release.sh --dry-run   # lista qué subiría
+bash packaging/scripts/publish-release.sh             # sube y verifica
+bash packaging/scripts/publish-release.sh --notify-panel   # y avisa al PANEL
+```
+
+Destino: `https://git.aduanasoft.com/api/packages/ADUANASOFT/generic/cloudrestoreas/<version>/`
+
+Tras subir, el script **relee la API de Gitea y compara el sha256 y el tamaño de cada
+artefacto** contra `release.json`. Si no coinciden falla: una publicación a medias no debe
+pasar por buena, porque el PANEL rechazaría la descarga por hash y el error aparecería
+mucho después, al intentar instalar.
+
+Los paquetes genéricos son **inmutables**: reintentar la misma versión da HTTP 409. Lo
+correcto es subir una versión nueva; `--force` borra y reemplaza, y solo aplica cuando la
+versión anterior nunca se instaló en ningún servidor.
+
+Todo en una sola tarea:
+```bash
+GITEA_TOKEN=xxxx ./build-all.sh --publish --notify-panel
+```
+`--publish` exige el build de **ambas** plataformas: publicar una versión a la que le falta
+una dejaría en el PANEL un release que no se le puede instalar a la mitad de los servidores,
+y corregirlo obligaría a quemar el número de versión.
+
+| Variable | Default | Para qué |
+|---|---|---|
+| `GITEA_TOKEN` | — | **Requerida.** PAT con scope `write:package` |
+| `GITEA_BASE_URL` | `https://git.aduanasoft.com` | Instancia de Gitea |
+| `GITEA_OWNER` | `ADUANASOFT` | Organización dueña del paquete |
+| `CRAS_PACKAGE` | `cloudrestoreas` | Nombre del paquete genérico |
+| `PANEL_API_URL` | — | Solo con `--notify-panel` |
+| `CLOUDRESTORE_API_TOKEN` | — | Solo con `--notify-panel` (token de servicio del PANEL) |
+
+Siguiente paso, en el PANEL: **/versiones-cras → Sincronizar con Gitea → Activar**, y de
+ahí **Instalar / Actualizar** por servidor.
+
+---
+
+## 6. Instalación / despliegue
+
+Lo normal es que el PANEL instale por SSH desde `/versiones-cras`, sembrando además las
+credenciales. Lo de abajo es el camino manual y lo que el PANEL ejecuta por dentro.

 ### Linux — `install.sh` (no instala nada del sistema)

 ```bash
-tar xzf CloudRestoreAS-linux.tar.gz && cd CloudRestoreAS
+tar xzf CloudRestoreAS-<version>-linux-x86_64.tar.gz && cd CloudRestoreAS

 sudo ./install.sh --service     # servicio systemd 24/7 headless (recomendado en servidor)
     ./install.sh --desktop      # autostart .desktop (requiere sesión gráfica)
@@ -95,6 +160,9 @@ sudo ./install.sh --service     # servicio systemd 24/7 headless (recomendado en
 ```
 Variables: `PREFIX=/opt/cloudrestoreas` (destino), `SERVICE_USER=<usuario>` (usuario del servicio).

+Detiene el servicio antes de reemplazar el binario (un ELF en ejecución da `ETXTBSY`) y lo
+vuelve a levantar si estaba activo.
+
 Servicio systemd:
 ```bash
 systemctl status cloudrestoreas
@@ -102,14 +170,45 @@ journalctl -u cloudrestoreas -f
 sudo systemctl restart cloudrestoreas    # tras editar config/.env
 ```

-### Windows
+### Windows — `install.ps1` (autocontenido, sin NSSM ni descargas)

-Copiar `CloudRestoreAS.exe` a una carpeta y ejecutarlo (o usar `install.ps1`). Al iniciar
-crea `config/` y un icono en la bandeja. Ver [packaging/LEEME.txt](packaging/LEEME.txt).
+```powershell
+Expand-Archive CloudRestoreAS-<version>-win-x86_64.zip -DestinationPath .
+cd CloudRestoreAS
+
+.\install.ps1 -Service      # tarea programada ONSTART como SYSTEM (24/7 headless)
+.\install.ps1 -Desktop      # arranque al iniciar sesión (tarea ONLOGON de la app)
+.\install.ps1               # solo instala + bootstrap
+Get-Help .\install.ps1 -Detailed
+```
+Parámetros: `-Prefix` (default `C:\Aduanasoft\CloudRestoreAS`), `-PanelEnvFile`.
+
+`-Service` requiere PowerShell **como Administrador** (la tarea corre como SYSTEM). El
+arranque 24/7 se resuelve con una tarea programada, no con NSSM: descargarlo violaría la
+regla de que en el servidor destino no se instala ni se baja nada.
+
+> `scripts/dev-setup.ps1` es otra cosa: prepara el entorno de **desarrollo** (Python, venv,
+> `requirements.txt`) para correr `python runner.py`. No sirve para desplegar el binario.
+
+### Siembra de credenciales del PANEL
+
+Ambos instaladores aceptan un archivo `KEY=valor` con las claves `CLOUDRESTORE_PANEL_*`,
+que fusionan en `config/.env` (replace-or-append, idempotente, con lista blanca) y luego
+borran:
+
+```bash
+./install.sh --service --panel-env-file /tmp/panel.env
+```
+```powershell
+.\install.ps1 -Service -PanelEnvFile C:\Temp\panel.env
+```
+
+Va por archivo y no por argumentos a propósito: un token en la línea de comandos queda
+visible en `ps` y en el historial del servidor destino.

 ---

-## 6. Ejecución manual y flags del binario
+## 7. Ejecución manual y flags del binario

 ```bash
 # Linux servidor sin pantalla (headless): motor de restauración sin GUI
@@ -124,13 +223,14 @@ QT_QPA_PLATFORM=offscreen ./CloudRestoreAS --start-engine --headless
 | `--start-engine` | Inicia el motor de restauración al arrancar |
 | `--headless` | Fuerza modo sin interfaz (Qt `offscreen`), para servidores sin display |
 | `--minimized` | Inicia minimizado en la bandeja |
+| `--version` | Imprime `CloudRestoreAS <version> (<platform>/<arch>)` y termina. En Windows requiere consola del padre (el `.exe` es `console=False`); el instalador remoto prefiere leer `config/.version` |
 | `QT_QPA_PLATFORM=offscreen` | Plataforma Qt sin display (el binario ya cae a esto automáticamente si no hay `DISPLAY`/`WAYLAND_DISPLAY` en Linux) |

 En Linux sin `DISPLAY`, el binario selecciona `offscreen` **solo**; con display usa `xcb`.

 ---

-## 7. Configuración (primera ejecución)
+## 8. Configuración (primera ejecución)

 El binario crea automáticamente: `config/`, `config/.env`, `Entrada/`, `Procesados/`,
 `Fallados/`, `Temp/`. Editar `config/.env`:
@@ -147,7 +247,7 @@ automáticamente según el formato del `data_folder`.

 ---

-## 8. Verificación de autocontención (contenedor pelado)
+## 9. Verificación de autocontención (contenedor pelado)

 Confirma que el binario Linux corre sin instalar NADA del sistema:

@@ -166,19 +266,23 @@ Esperado: arranca en `offscreen` sin errores Qt, `0` deps ODBC faltantes, `7zz`

 ---

-## 9. Artefactos y ubicaciones
+## 10. Artefactos y ubicaciones

 | Ruta | Qué es |
 |---|---|
 | `dist/CloudRestoreAS` | Binario Linux onefile |
 | `dist/CloudRestoreAS.exe` | Ejecutable Windows onefile |
-| `dist/release/*.tar.gz` / `*.zip` | Paquetes de despliegue (binario + instalador + docs) |
+| `dist/release/CloudRestoreAS-<version>-*.{tar.gz,zip}` | Paquetes de despliegue publicables (binario + instalador + docs) |
+| `dist/release/release.json` | Manifiesto de la versión (lo consume `publish-release.sh`) |
+| `dist/release/SHA256SUMS` | Checksums de los paquetes |
+| `config/.version` | Sello de la versión que corrió (lo lee el instalador remoto por SFTP) |
+| `config/.bundled_deps` | Sello del `bundled-versions.json` desplegado; si cambia, se re-copian `config/7zip` y `config/odbc` |
 | `packaging/bundled/{linux,windows}/` | Deps embebidas (generadas en build; git-ignored) |
 | `venv-linux/`, `venv-windows/` | Entornos virtuales de build (git-ignored) |

 ---

-## 10. Scripts de referencia rápida
+## 11. Scripts de referencia rápida

 | Script | Propósito |
 |---|---|
@@ -186,6 +290,8 @@ Esperado: arranca en `offscreen` sin errores Qt, `0` deps ODBC faltantes, `7zz`
 | `build.sh` / `build.ps1` | Build individual Linux / Windows |
 | `packaging/scripts/docker-build-linux.sh` | Build Linux en contenedor controlado |
 | `packaging/scripts/download-bundled-deps.sh` / `.ps1` | Descarga+embebe deps |
-| `packaging/scripts/package-release.sh` | Genera `.tar.gz` / `.zip` |
-| `install.sh` / `install.ps1` | Instalador Linux / Windows |
+| `packaging/scripts/package-release.sh` | Genera los paquetes versionados + `SHA256SUMS` + `release.json` |
+| `packaging/scripts/publish-release.sh` | Publica en los paquetes genéricos de Gitea y verifica el sha256 |
+| `install.sh` / `install.ps1` | Instalador de **despliegue** Linux / Windows (autocontenidos) |
+| `scripts/dev-setup.ps1` | Entorno de **desarrollo** en Windows (Python + venv). No sirve para desplegar |
 | `packaging/linux/cloudrestoreas.service` | Unit systemd (24/7 headless) |