ProxMenux/docs/01.PROXMENUX_REVIEW.md

---

# **Análisis Completo del proyecto ProxMenux**

## **1. Estructura General del Proyecto**

### **Archivos Principales**
- **[install_proxmenux.sh](cci:7://file:///home/debian/src/ProxMenuxDotDeb/install_proxmenux.sh:0:0-0:0)**: Script de instalación principal (723 líneas)
- **[menu](cci:7://file:///home/debian/src/ProxMenuxDotDeb/menu:0:0-0:0)**: Script principal que se instala como comando del sistema (93 líneas)
- **[version.txt](cci:7://file:///home/debian/src/ProxMenuxDotDeb/version.txt:0:0-0:0)**: Control de versiones (actual: 1.1.7)

### **Directorios Principales**
```
ProxMenuxDotDeb/
├── scripts/           # 122 archivos de scripts bash
│   ├── menus/        # 13 scripts de menús
│   ├── lxc/          # 6 scripts para contenedores LXC
│   ├── vm/           # 13 scripts para máquinas virtuales
│   ├── storage/      # 9 scripts de almacenamiento
│   ├── share/        # 12 scripts para compartir recursos
│   ├── utilities/    # 6 utilidades del sistema
│   ├── global/       # 10 funciones comunes
│   ├── backup_restore/ # 6 scripts de respaldo
│   ├── post_install/ # 3 scripts post-instalación
│   └── gpu_tpu/      # Scripts para hardware gráfico
├── web/              # 136 archivos - Dashboard Next.js
├── AppImage/         # 54 archivos - ProxMenux Monitor
├── json/             # Archivos de caché de traducciones
├── lang/             # Archivos de idioma
├── guides/           # 5 guías de usuario
└── images/           # 7 imágenes del proyecto
```

---

## **2. Flujo de Instalación**

### **Script: [install_proxmenux.sh](cci:7://file:///home/debian/src/ProxMenuxDotDeb/install_proxmenux.sh:0:0-0:0)**

**Fase 1: Inicialización**
- Verifica permisos root (línea 716-719)
- Carga [utils.sh](cci:7://file:///home/debian/src/ProxMenuxDotDeb/scripts/utils.sh:0:0-0:0) desde GitHub (línea 54-57)
- Limpia archivos corruptos de configuración (línea 59-68)

**Fase 2: Detección de Instalación Existente**
- Función [check_existing_installation()](cci:1://file:///home/debian/src/ProxMenuxDotDeb/install_proxmenux.sh:70:0-106:1) (línea 71-107)
- Detecta 4 tipos: `none`, `normal`, `translation`, `unknown`
- Verifica entorno virtual Python en `/opt/googletrans-env`
- Verifica configuración de idioma en `/usr/local/share/proxmenux/config.json`

**Fase 3: Selección de Versión**
- **Versión Normal** (opción 1):
  - Dependencias: `dialog`, `curl`, `jq`
  - Solo inglés
  - Más ligera y rápida
  
- **Versión con Traducción** (opción 2):
  - Dependencias adicionales: `python3`, `python3-venv`, `python3-pip`
  - Instala `googletrans==4.0.0-rc1` en entorno virtual
  - Soporte multiidioma: en, es, fr, de, it, pt
  - **Nota**: No compatible con Proxmox VE 9+ (línea 639-658)

**Fase 4: Instalación Normal** ([install_normal_version()](cci:1://file:///home/debian/src/ProxMenuxDotDeb/install_proxmenux.sh:402:0-484:1))
1. Instala dependencias básicas
2. Crea directorios:
   - `/usr/local/bin` (ejecutables)
   - `/usr/local/share/proxmenux` (archivos del sistema)
3. Descarga desde GitHub:
   - `utils.sh` → `/usr/local/share/proxmenux/utils.sh`
   - `menu` → `/usr/local/bin/menu`
   - `version.txt` → `/usr/local/share/proxmenux/version.txt`
4. Instala ProxMenux Monitor (AppImage)

**Fase 5: Instalación con Traducción** (`install_translation_version()`)
- Pasos adicionales:
  - Selector de idioma interactivo (línea 234-273)
  - Crea entorno virtual Python en `/opt/googletrans-env`
  - Instala googletrans con pip
  - Descarga `cache.json` con traducciones precargadas
  - Sistema de caché para reducir llamadas a la API de traducción

**Fase 6: ProxMenux Monitor**
- Descarga AppImage desde GitHub (línea 317-360)
- Verifica checksum SHA256 (línea 333-351)
- Crea servicio systemd `/etc/systemd/system/proxmenux-monitor.service`
- Puerto por defecto: 8008
- Se ejecuta como usuario root
- Auto-inicio en boot

---

## **3. Funcionamiento del Comando `menu`**

### **Script Principal: `/usr/local/bin/menu`**

**Flujo de Ejecución:**

1. **Carga de Configuración** (línea 33-44):
   ```bash
   REPO_URL="https://raw.githubusercontent.com/MacRimi/ProxMenux/main"
   BASE_DIR="/usr/local/share/proxmenux"
   source "$UTILS_FILE"
   ```

2. **Sistema de Traducción** (línea 89-92):
   - Carga idioma desde `config.json`
   - Inicializa caché de traducciones
   - Función `translate()` en `utils.sh`

3. **Verificación de Actualizaciones** (línea 48-80):
   - Compara versión local vs remota
   - Prompt interactivo para actualizar
   - Descarga y ejecuta nuevo `install_proxmenux.sh` si hay actualización

4. **Ejecución del Menú Principal** (línea 84-86):
   ```bash
   exec bash <(curl -fsSL "$REPO_URL/scripts/menus/main_menu.sh")
   ```

**Importante**: El comando `menu` **NO ejecuta scripts locales**, siempre descarga desde GitHub.

---

## **4. Sistema de Menús**

### **Menú Principal: `scripts/menus/main_menu.sh`**

**Compatibilidad PVE 9** (línea 26-64):
- Detecta versión de Proxmox
- Si PVE 9+ y tiene traducciones instaladas → fuerza reinstalación en versión normal
- Previene errores de compatibilidad

**Opciones del Menú** (línea 97-111):
```
1. Settings post-install Proxmox    → menu_post_install.sh
2. Hardware: GPUs and Coral-TPU     → hw_grafics_menu.sh
3. Create VM from template          → create_vm_menu.sh
4. Disk and Storage Manager         → storage_menu.sh
5. Mount and Share Manager          → share_menu.sh
6. Proxmox VE Helper Scripts        → menu_Helper_Scripts.sh
7. Network Management               → network_menu.sh
8. Utilities and Tools              → utilities_menu.sh
h. Help and Info Commands           → help_info_menu.sh
s. Settings                         → config_menu.sh
0. Exit
```

**Patrón de Ejecución**:
```bash
exec bash <(curl -s "$REPO_URL/scripts/menus/submenu.sh")
```

Todos los menús descargan y ejecutan scripts desde GitHub en tiempo real.

---

## **5. Scripts Locales vs Remotos**

### **Estado Actual**
- **Scripts locales**: Están presentes en el repositorio (122 archivos)
- **Ejecución**: Siempre desde GitHub mediante `curl`
- **Ventaja actual**: Actualizaciones automáticas sin reinstalar
- **Desventaja**: Requiere conexión a internet constante

### **Scripts Principales Disponibles Localmente**

**Gestión de VMs** (`scripts/vm/`):
- `create_vm.sh` - Crear VMs
- `synology.sh` (39KB) - Instalación Synology DSM
- `zimaos.sh` (40KB) - Instalación ZimaOS
- `uupdump_creator.sh` - Creador de ISOs Windows
- `select_windows_iso.sh`, `select_linux_iso.sh`, `select_nas_iso.sh`

**Gestión de LXC** (`scripts/lxc/`):
- `lxc-manual-guide.sh` - Guía manual
- `lxc-privileged-to-unprivileged.sh`
- `lxc-unprivileged-to-privileged.sh`

**Almacenamiento** (`scripts/storage/`):
- `disk-passthrough.sh` - Passthrough disco a VM
- `disk-passthrough_ct.sh` - Passthrough disco a LXC (22KB)
- `import-disk-image.sh` - Importar imágenes
- `format-disk.sh`, `mount-disk-on-host.sh`

**Compartir Recursos** (`scripts/share/`):
- `lxc-mount-manager_minimal.sh` (35KB) - Gestión mount points
- `nfs_host.sh` (35KB) - Servidor NFS en host
- `samba_host.sh` (52KB) - Servidor Samba en host
- `nfs_client.sh`, `samba_client.sh` - Clientes en LXC
- `local-shared-manager.sh` - Directorios compartidos locales

**Post-Instalación** (`scripts/post_install/`):
- `auto_post_install.sh` (29KB) - Automatizado sin interacción
- `customizable_post_install.sh` (148KB) - Personalizable
- `uninstall-tools.sh` (34KB) - Desinstalador

**Utilidades** (`scripts/utilities/`):
- `upgrade_pve8_to_pve9.sh` (35KB) - Upgrade PVE 8→9
- `system_utils.sh` (20KB) - Instalador de utilidades
- `proxmox_update.sh` - Actualización de Proxmox

**Red** (`scripts/menus/network_menu.sh`):
- 43KB de funcionalidades de red
- Optimizaciones para LXC+NFS

**Global** (`scripts/global/`):
- `update-pve.sh`, `update-pve8.sh`, `update-pve9_2.sh`
- `remove-banner-pve8.sh`, `remove-banner-pve9.sh`
- `share-common.func` (30KB) - Funciones compartidas

---

## **6. Sistema de Utilidades: `utils.sh`**

### **Funciones Principales**

**Interfaz Visual** (línea 50-71):
- Definición de colores ANSI
- Códigos de estilo para terminal
- Spinner animado (línea 75-88)

**Mensajes Estandarizados**:
- `msg_info()` - Info con spinner
- `msg_ok()` - Éxito (checkmark verde)
- `msg_error()` - Error (rojo)
- `msg_warn()` - Advertencia (amarillo)
- `msg_title()` - Títulos
- `type_text()` - Efecto máquina de escribir

**Sistema de Traducción** (línea 232-305):
```bash
translate() {
    # Si idioma es "en" → retorna texto original
    # Busca en caché local (cache.json)
    # Si no existe → llama a googletrans vía Python
    # Guarda en caché para futuras traducciones
    # Limpia prefijos de contexto
}
```

**Contexto de Traducción** (línea 48):
```bash
TRANSLATION_CONTEXT="Context: Technical message for Proxmox and IT. Translate:"
```

**Logo ASCII** (línea 314-400):
- Dos versiones: terminal noVNC y SSH
- Detección automática del entorno
- Diseño en ASCII art con colores

---

## **7. ProxMenux Monitor**

### **Componente Web (AppImage)**

**Tecnología**:
- **Frontend**: Next.js 14, React 18, TypeScript
- **UI**: Radix UI + shadcn/ui + Tailwind CSS
- **Gráficos**: Recharts
- **Backend**: Flask (Python) para recolección de datos del sistema
- **Empaquetado**: AppImage (10.3 MB)

**Características**:
- Dashboard en tiempo real
- Monitoreo de CPU, RAM, temperatura
- Estado de VMs y LXC containers
- Gestión de almacenamiento visual
- Estadísticas de red
- Logs del sistema
- Tema oscuro/claro
- Responsive design
- Puerto: 8008

**Servicio Systemd**:
```ini
[Unit]
Description=ProxMenux Monitor - Web Dashboard
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/usr/local/share/proxmenux
ExecStart=/usr/local/share/proxmenux/ProxMenux-Monitor.AppImage
Restart=on-failure
RestartSec=10
Environment="PORT=8008"
```

**Estado**: Se instala automáticamente en ambas versiones (normal y traducción)

---

## **8. Sistema de Configuración**

### **Archivos de Configuración**

**`/usr/local/share/proxmenux/config.json`**:
- Estado de instalación de componentes
- Idioma seleccionado
- Timestamps de instalación
- Estados: `installed`, `already_installed`, `failed`

**Componentes Rastreados** (línea 201):
```json
{
  "dialog": {"status": "installed", "timestamp": "..."},
  "curl": {"status": "already_installed", "timestamp": "..."},
  "jq": {"status": "installed", "timestamp": "..."},
  "python3": {"status": "installed", "timestamp": "..."},
  "virtual_environment": {"status": "created", "timestamp": "..."},
  "googletrans": {"status": "installed", "timestamp": "..."},
  "proxmenux_monitor": {"status": "installed", "timestamp": "..."},
  "language": "es"
}
```

**`/usr/local/share/proxmenux/cache.json`**:
- Traducciones cacheadas (100 KB)
- Formato: `{"texto_original": {"es": "traducción", "fr": "traduction"}}`
- Reduce llamadas a Google Translate API

**`/usr/local/share/proxmenux/installed_tools.json`**:
- Registro de herramientas post-instalación
- Usado por el desinstalador

---

## **9. Funcionalidades Destacadas**

### **Post-Instalación Automatizada**
- **Optimizaciones de repositorios**: Limpia duplicados, configura repos gratuitos
- **Eliminación de banner de suscripción**: Con respaldo y reversión
- **Optimización de memoria y kernel**: Ajustes según RAM disponible
- **Log2RAM**: Instalación automática en SSD/NVMe
- **Network tuning**: Optimización de stack de red
- **Límites del sistema**: Aumenta límites de archivos y procesos
- **Configuración de journald**: Ajustada para Log2RAM
- **Entropía**: Mejora generación de números aleatorios
- **Aliases bash**: Personalización del entorno

### **Gestión de Compartición de Recursos**
**Enfoque**: Mount Points LXC (Host ↔ Container)
- Detección automática de tipo de filesystem
- Mapeo UID/GID para contenedores unprivileged
- Visualización de mount points existentes
- Eliminación segura con verificación

**Configuraciones disponibles**:
- NFS: Host, Client LXC, Server LXC
- Samba: Host, Client LXC, Server LXC
- Directorios locales compartidos

### **Hardware Especializado**
- **Coral TPU**: Instalación de drivers compatible con PVE 8 y 9
- **GPUs**: Passthrough y configuración para VMs y LXC
- **iGPU**: Configuración para contenedores LXC

### **Upgrade PVE 8 → 9**
- Script de 35 KB con verificaciones exhaustivas
- Guía manual interactiva
- Checker de compatibilidad

---

## **10. Arquitectura de Ejecución**

### **Patrón de Descarga Dinámica**

**Todos los scripts siguen este patrón**:
```bash
exec bash <(curl -s "$REPO_URL/scripts/path/to/script.sh")
```

**Ventajas**:
- ✅ Usuarios siempre tienen la última versión
- ✅ No requiere reinstalación para actualizaciones
- ✅ Hotfixes inmediatos
- ✅ Control centralizado de versiones

**Consideraciones**:
- ⚠️ Requiere internet en cada ejecución
- ⚠️ Dependencia de disponibilidad de GitHub
- ⚠️ No funciona offline
- ⚠️ Los scripts locales del repo no se usan directamente

### **Sistema de Versionado**
- `version.txt` en repo: versión remota
- `/usr/local/share/proxmenux/version.txt`: versión local instalada
- Check en cada ejecución del comando `menu`
- Prompt para actualizar si hay nueva versión

---

## **11. Flujo de Navegación**

```
Comando: menu
    ↓
Verifica actualizaciones
    ↓
Carga utils.sh y traducciones
    ↓
Descarga main_menu.sh desde GitHub
    ↓
Usuario selecciona opción
    ↓
Descarga submenu correspondiente desde GitHub
    ↓
Usuario selecciona acción
    ↓
Descarga y ejecuta script específico desde GitHub
    ↓
Retorna al menú anterior
```

**Ejemplo de navegación**:
```
menu → main_menu.sh
  → opción 5: share_menu.sh
    → opción 4: lxc-mount-manager_minimal.sh (35KB)
      → Ejecuta acciones
      → Retorna a share_menu.sh
    → opción 0: Retorna a main_menu.sh
  → opción 0: Exit
```

---

## **12. Integración con Comunidad**

### **Scripts de la Comunidad Integrados**

**Proxmox VE Helper-Scripts**:
- Post-install script oficial
- Ejecutado desde: `https://github.com/community-scripts/ProxmoxVE`

**Xshok-proxmox** (fork):
- Post-install alternativo
- Descarga desde fork de MacRimi

**Elementos compartidos**:
- Funciones de `utils.sh` basadas en Helper-Scripts
- Misma filosofía de mensajes estandarizados
- Licencia MIT compatible

---

## **13. Sistema de Desinstalación**

### **Función: `uninstall_proxmenux()`** (línea 109-161)

**Proceso**:
1. Confirmación interactiva (whiptail)
2. Desinstala googletrans y entorno virtual Python
3. Selector de dependencias a eliminar (python3, python3-venv, pip)
4. Elimina `/usr/local/bin/menu`
5. Elimina `/usr/local/share/proxmenux/`
6. Restaura `.bashrc` desde backup
7. Restaura `/etc/motd` desde backup

**Tool-specific uninstaller**: `scripts/post_install/uninstall-tools.sh`
- Lee `installed_tools.json`
- Permite desinstalar herramientas individualmente
- Restaura configuraciones originales

---

## **14. Estructura de Archivos JSON**

### **`json/cache.json`** (100 KB)
Traducciones precargadas para acelerar el sistema

### **`json/helpers_cache.json`** (273 KB)
Caché extendido, probablemente para Helper Scripts

### **`lang/cache.json`** (5.5 KB)
Caché de idiomas específico

### **`lang/en.lang`** y **`lang/es.lang`**
Archivos de idioma estáticos (4-5 KB cada uno)

---

## **15. Resumen de Componentes**

| Componente | Ubicación | Función |
|------------|-----------|---------|
| **Instalador** | `install_proxmenux.sh` | Instalación inicial y actualizaciones |
| **Comando principal** | `/usr/local/bin/menu` | Punto de entrada del usuario |
| **Utilidades** | `/usr/local/share/proxmenux/utils.sh` | Funciones compartidas |
| **Configuración** | `/usr/local/share/proxmenux/config.json` | Estado del sistema |
| **Caché traducciones** | `/usr/local/share/proxmenux/cache.json` | Traducciones cacheadas |
| **Entorno Python** | `/opt/googletrans-env/` | Traducción (solo versión translation) |
| **Monitor** | `/usr/local/share/proxmenux/ProxMenux-Monitor.AppImage` | Dashboard web |
| **Servicio Monitor** | `/etc/systemd/system/proxmenux-monitor.service` | Servicio systemd |
| **Scripts** | GitHub (descarga dinámica) | Todos los scripts funcionales |

---

## **Conclusión**

ProxMenuxDotDeb es un **sistema modular de gestión de Proxmox VE** que utiliza una arquitectura híbrida:

- **Núcleo local**: Comando `menu`, utilidades, sistema de configuración
- **Scripts remotos**: Toda la funcionalidad se descarga dinámicamente desde GitHub
- **Dashboard web**: AppImage independiente con Next.js + Flask
- **Sistema de traducción**: Opcional, basado en Python + googletrans + caché

El proyecto tiene **122 scripts bash** en el repositorio local que **podrían ejecutarse localmente**, pero actualmente **todos se descargan desde GitHub en tiempo de ejecución**. Esta arquitectura prioriza mantener a los usuarios actualizados sobre la ejecución offline.