CloudRecoveryAS/BUILD.md

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.

./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 (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. 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 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)

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:

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.

---

6. Ejecución manual y flags del binario

# 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:

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)