feature/generador-instaladores-linux-windows

2026-07-01 10:33:05 -06:00
parent 0d8d80d61d
commit 0c14f1166b
17 changed files with 802 additions and 90 deletions
--- a/BUILD.md
+++ b/BUILD.md
@@ -0,0 +1,191 @@
+# BUILD.md — Compilación, empaquetado y despliegue
+
+Referencia de **todos** los comandos, ejecutables y scripts para generar, empaquetar,
+instalar y verificar CloudRestoreAS en Windows y Linux.
+
+El ejecutable es **autocontenido**: no requiere Python, 7-Zip, driver ODBC ni librerías
+Qt instaladas en el equipo destino. Todo se embebe dentro del binario en tiempo de build.
+
+---
+
+## 1. Todo en una tarea (recomendado) — `build-all.sh`
+
+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 --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 --help
+```
+
+**Requisitos:**
+- Linux: **Docker** (usa `docker-build-linux.sh` en ubuntu:22.04).
+- Windows: **`powershell.exe`** accesible desde WSL + **Python 3.11+** instalado en Windows
+  (`build.ps1` lo auto-detecta en `%LOCALAPPDATA%\Programs\Python\Python31X`).
+- Es *fail-soft*: si no hay `powershell.exe`, compila solo Linux y avisa.
+
+> El build de Windows se hace sobre la ruta `\\wsl.localhost\...`, por eso tarda
+> (~15-18 min: pip install de PySide6 + PyInstaller). El de Linux (Docker, con deps
+> cacheadas) es rápido.
+
+`packaging/scripts/build-all.sh` es un wrapper que delega en este mismo script.
+
+---
+
+## 2. Builds individuales
+
+| Objetivo | Comando | Salida | Notas |
+|---|---|---|---|
+| **Linux (Docker, recomendado)** | `bash packaging/scripts/docker-build-linux.sh` | `dist/CloudRestoreAS` | ubuntu:22.04 con todas las deps + `patchelf`; garantiza autocontención |
+| **Linux (host)** | `./build.sh` | `dist/CloudRestoreAS` | Requiere que el host tenga las libs Qt/ODBC; usar solo si no hay Docker |
+| **Windows** | `.\build.ps1` (en Windows/PowerShell) | `dist\CloudRestoreAS.exe` | Auto-detecta Python 3.11+; crea `venv-windows` |
+
+Ambos usan el mismo spec: [packaging/CloudRestoreAS.spec](packaging/CloudRestoreAS.spec) (PyInstaller **onefile**, `console=False`).
+
+---
+
+## 3. Dependencias embebidas (build-time)
+
+Se descargan e integran al binario. No se instalan en el destino.
+
+| Script | Qué embebe |
+|---|---|
+| `packaging/scripts/download-bundled-deps.sh` (Linux) | `7zz` (7-Zip Linux), driver **MS ODBC 18** + unixODBC + Kerberos/GSSAPI + libltdl + OpenSSL, y cluster **Qt xcb/X11 + EGL**. Aplica `patchelf --set-rpath '$ORIGIN'` a las `.so` del cluster ODBC para que resuelvan entre sí. |
+| `packaging/scripts/download-bundled-deps.ps1` (Windows) | `7z.exe` y `msodbcsql18.dll`. |
+
+Versiones/URLs en [packaging/bundled-versions.json](packaging/bundled-versions.json).
+Los binarios quedan en `packaging/bundled/{linux,windows}/` (git-ignored, se generan en el build).
+
+**Ubicación en runtime** (creada por el bootstrap en la primera ejecución):
+- `config/7zip/7zz` — extractor.
+- `config/odbc/lib/` — driver ODBC + toda su cadena (resuelven por `$ORIGIN`).
+- Cluster Qt xcb/EGL — dentro del onefile, en `PySide6/Qt/lib`.
+
+---
+
+## 4. Empaquetado — `package-release.sh`
+
+```bash
+bash packaging/scripts/package-release.sh
+```
+
+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` |
+
+---
+
+## 5. Instalación / despliegue
+
+### Linux — `install.sh` (no instala nada del sistema)
+
+```bash
+tar xzf CloudRestoreAS-linux.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)
+     ./install.sh                # solo instala + bootstrap; lo corres a mano
+     ./install.sh --help
+```
+Variables: `PREFIX=/opt/cloudrestoreas` (destino), `SERVICE_USER=<usuario>` (usuario del servicio).
+
+Servicio systemd:
+```bash
+systemctl status cloudrestoreas
+journalctl -u cloudrestoreas -f
+sudo systemctl restart cloudrestoreas    # tras editar config/.env
+```
+
+### Windows
+
+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).
+
+---
+
+## 6. Ejecución manual y flags del binario
+
+```bash
+# Linux servidor sin pantalla (headless): motor de restauración sin GUI
+QT_QPA_PLATFORM=offscreen ./CloudRestoreAS --start-engine --headless
+
+# Linux con escritorio o Windows: abre la GUI normal
+./CloudRestoreAS
+```
+
+| Flag / variable | Efecto |
+|---|---|
+| `--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 |
+| `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)
+
+El binario crea automáticamente: `config/`, `config/.env`, `Entrada/`, `Procesados/`,
+`Fallados/`, `Temp/`. Editar `config/.env`:
+
+```
+CLOUDRESTORE_AUTO_START=true            # el motor arranca solo
+CLOUDRESTORE_PANEL_API_URL=...          # servicio PANEL_BASES_ANEXO24 (enrutamiento)
+CLOUDRESTORE_PANEL_API_TOKEN=...
+CLOUDRESTORE_PANEL_INSTANCE_KEY=...
+```
+El PANEL entrega el servidor SQL destino y su `data_folder`. Con SQL Server sobre Linux
+serán rutas POSIX (p. ej. `/var/opt/mssql/data`); el `RESTORE ... MOVE` adapta el separador
+automáticamente según el formato del `data_folder`.
+
+---
+
+## 8. Verificación de autocontención (contenedor pelado)
+
+Confirma que el binario Linux corre sin instalar NADA del sistema:
+
+```bash
+docker run --rm -v "$PWD/dist:/dist:ro" debian:12-slim bash -c '
+  cp /dist/CloudRestoreAS /root/app && cd /root
+  QT_QPA_PLATFORM=offscreen timeout 12 ./app --headless --start-engine 2>&1 | \
+    grep -iE "offscreen|Ventana principal|Traceback|platform plugin"
+  # ODBC: driver + cadena resuelven por $ORIGIN (debe dar 0)
+  ldd /root/config/odbc/lib/libmsodbcsql-18*.so* 2>&1 | grep -c "not found"
+  # 7-Zip embebido
+  /root/config/7zip/7zz | head -1
+'
+```
+Esperado: arranca en `offscreen` sin errores Qt, `0` deps ODBC faltantes, `7zz` ejecuta.
+
+---
+
+## 9. 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) |
+| `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
+
+| Script | Propósito |
+|---|---|
+| `build-all.sh` | **Todo en uno** (Windows + Linux + paquetes) desde WSL |
+| `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/linux/cloudrestoreas.service` | Unit systemd (24/7 headless) |