Guía de instalación — MoniSafe

Control financiero personal que importa extractos CSV de Santander Uruguay y otros bancos, autocategoriza comercios y genera analítica de ahorro.

Versión actual del paquete: v1.9.7 · Funciona 100% offline (sin CDNs, sin internet)

Contenido

  1. Instalación en Windows
  2. Instalación en Linux
  3. Primeros pasos dentro de la app
  4. Cómo funcionan las actualizaciones
  5. Solución de problemas
  6. Dónde viven tus datos

🪟 1 · Instalación en Windows

El instalador es el propio MoniSafe.exe (un solo archivo hace todo: instala, lanza y desinstala). No necesita permisos de administrador y no toca tu registro de datos personales.

Requisitos

✅ Windows 10 / 11 (64 bits)
✅ Sin conexión a internet para funcionar
👀 Microsoft Visual C++ Redistributable x64
⛰️ Componente requerido: VC++ Redistributable Si Windows te muestra “Falta VCRUNTIME140.dll” al abrir la app, descargá e instalá el Microsoft Visual C++ Redistributable (x64) desde el sitio de Microsoft. La mayoría de los equipos ya lo tienen.

Pasos

  1. Descargá el archivo MoniSafe-win64-v1.9.7.zip.
  2. Hacé clic derecho → Extraer todo en cualquier carpeta (por ejemplo Descargas o el Escritorio). No hace falta ejecutar desde una ubicación especial.
  3. Doble clic en MoniSafe.exe que quedó dentro:
SituaciónQué hace
Primera vez (desde la carpeta descomprimida)Se comporta como instalador: copia el programa a %LOCALAPPDATA%\Programs\MoniSafe, crea los accesos directos (Escritorio + Menú Inicio), registra el desinstalador en Windows y arranca la app.
Ejecuciones siguientes (desde el acceso directo o la carpeta instalada)Se comporta como lanzador: levanta el servidor local, abre tu navegador y coloca a MoniSafe en la bandeja/activa solo una instancia.
Si ya hay una instancia corriendoNo arranca otra: solo reabre la pestaña del navegador en la app ya activa.

Actualizar (instalar una versión nueva encima)

  1. Cerrate la app si está abierta: cerrar la ventana del navegador no detiene el servidor; si MoniSafe está corriendo, el instalador la cierra automáticamente (mata solo el proceso de MoniSafe, no toca otros programas).
  2. Descargá el nuevo MoniSafe-win64-vX.Y.Z.zip y descomprimilo.
  3. Doble clic en su MoniSafe.exe.
  4. El instalador reemplaza los archivos del programa sin borrar tus datos (quedan intactos en %APPDATA%\MoniSafe, incluyendo tu clave de cifrado y la base de datos).
⚠️ Cómo verificar que la app quedó detenida Si no confiás en el cierre automático, abrí el Administrador de tareas y confirmá que no haya procesos MoniSafe.exe ni php.exe (de MoniSafe) antes de instalar. Ante la duda, reiniciá o cerrá la sesión de Windows.

Desinstalar

  1. Configuración de Windows → Aplicaciones → buscá MoniSafe → Desinstalar.
  2. O ejecutá %LOCALAPPDATA%\Programs\MoniSafe\uninstall.cmd.
✅ Tus datos NO se borran al desinstalar El desinstalador nunca elimina %APPDATA%\MoniSafe. Si reinstalás, volvés a encontrar tu base y tus cuentas. Para borrarlos de verdad tenés que eliminar esa carpeta manualmente.

🐧 2 · Instalación en Linux

El paquete Linux no trae un instalador gráfico estilo Windows, pero hace lo mismo con un ejecutable: el binario MoniSafe es un lanzador de doble modo (instalador + lanzador). No requiere permisos de root.

Requisitos

✅ Distribución Linux de 64 bits
☕ PHP CLI versión 8+ con pdo_sqlite, openssl y mbstring
☕ PHP es obligatorio (el paquete Linux no lo incluye) A diferencia del de Windows, la versión Linux usa el PHP instalado en tu sistema. Instalalo con el gestor de paquetes: 
# Ubuntu / Debian
sudo apt update
sudo apt install php-cli php-sqlite3 php-mbstring

# Fedora
sudo dnf install php-cli php-pdo php-mbstring
Comprobá que quedó bien: php -v (debe mostrar PHP 8.0 o superior).

Pasos

  1. Descargá MoniSafe-linux64-v1.9.7.tar.gz.
  2. Descomprimilo y entrá a la carpeta: 
    tar -xzf MoniSafe-linux64-v1.9.7.tar.gz
cd MoniSafe
  3. Dale permiso de ejecución al binario (solo la primera vez): 
    chmod +x MoniSafe
  4. Ejecutalo desde esa carpeta: 
    ./MoniSafe
SituaciónQué hace
Primera vezComo corre desde una carpeta que no es la de instalación y tiene la carpeta app/ al lado, se comporta como instalador: copia el programa a ~/.local/share/MoniSafe, crea el acceso directo .desktop (aparece en el menú de aplicaciones) y el desinstalador uninstall.sh.
Ejecuciones siguientes (acceso directo o ~/.local/share/MoniSafe/MoniSafe)Actúa como lanzador: levanta el servidor local y abre tu navegador predeterminado.

El acceso directo

El instalador lo crea automáticamente en ~/.local/share/applications/monisafe.desktop (o en $XDG_DATA_HOME/applications/ si definiste esa variable), con la línea Icon= apuntando al ícono que viaja dentro del paquete (app/assets/img/app-icon.png, 256×256). Gracias a ese archivo, MoniSafe aparece en el menú de aplicaciones de tu entorno de escritorio (GNOME, KDE, XFCE, etc.) con su ícono, listo para ejecutar con un clic — sin terminal.

Crearlo a mano (si no apareció en el menú)
  1. Creá el archivo del acceso directo: 
    mkdir -p ~/.local/share/applications
nano ~/.local/share/applications/monisafe.desktop
  2. Pegá este contenido (reemplazá TU_USUARIO por tu nombre de usuario): 
    [Desktop Entry]
Type=Application
Name=MoniSafe
Comment=Control Financiero Personal
Icon=/home/TU_USUARIO/.local/share/MoniSafe/app/assets/img/app-icon.png
Exec=/home/TU_USUARIO/.local/share/MoniSafe/MoniSafe
Path=/home/TU_USUARIO/.local/share/MoniSafe
Terminal=false
Categories=Office;Finance;
  3. Dale permiso de ejecución y refrescá el menú: 
    chmod +x ~/.local/share/applications/monisafe.desktop
update-desktop-database ~/.local/share/applications
Si al crear el acceso directo manual no se reflejara el ícono, cerrá sesión y volvé a entrar (o reiniciá el panel del escritorio) para que recargue el catálogo de aplicaciones.
Anclarlo a la barra o al Escritorio
GNOME: buscá MoniSafe en la grilla de aplicaciones, clic derecho → Agregar a Favoritos.
KDE / XFCE: arrastrá el icono de MoniSafe desde el menú hacia la barra de tareas o al fondo del escritorio.

Detener la app (servicio local)

MoniSafe corre un servidor local en tu máquina (php -S 127.0.0.1:8618). Cerrar la pestaña del navegador no detiene el servidor: la app sigue activa hasta que detenés el proceso. Necesitás detenerla antes de actualizar o desinstalar (en Linux, a diferencia de Windows, el instalador no la cierra automáticamente).

  1. En la terminal: 
    pkill -f MoniSafe
  2. O desde el Monitor del sistema (o htop): buscá el proceso MoniSafe y terminálo.
  3. Verificá que no quede nada escuchando (esto comprueba el puerto 8618): 
    ss -ltnp | grep 8618 || echo "detenido OK"

Actualizar (instalar una versión nueva encima)

  1. Detené la app tal como se explica arriba (obligatorio: no hay cierre automático en Linux).
  2. Descargá el nuevo MoniSafe-linux64-vX.Y.Z.tar.gz y descomprimilo en una carpeta nueva: 
    tar -xzf MoniSafe-linux64-vX.Y.Z.tar.gz
cd MoniSafe
  3. Ejecutá el instalador de la nueva versión: 
    chmod +x MoniSafe
./MoniSafe
  4. Se copia el programa nuevo sobre ~/.local/share/MoniSafe y se refresca el acceso directo, sin borrar tus datos (quedan intactos en ~/.monisafe).

Desinstalar

  1. Detené la app primero (si quedó abierta): pkill -f MoniSafe.
  2. Ejecutá el desinstalador: 
    ~/.local/share/MoniSafe/uninstall.sh
✅ Tus datos NO se borran al desinstalar El desinstalador avisa la desinstalación y quita el programa, pero conserva tus datos en ~/.monisafe (base de datos y clave de cifrado). Para borrarlos de verdad: rm -rf ~/.monisafe.

🚀 3 · Primeros pasos dentro de la app

  1. Creá tu cuenta: al abrir la app por primera vez no hay usuarios registrados. El primer usuario que se registre pasa a ser administrador (no existen cuentas ni contraseñas por defecto).
  2. Importá tus extractos: andá a Importar y subí los CSV de tu banco.
    • Santander Uruguay (débito, crédito o saldos): se importa automáticamente y se reconoce solo.
    • Otros bancos (ej. BROU): la primera vez un asistente te pide mapear las columnas; ese mapeo se guarda como perfil y las próximas subidas del mismo banco se importan solas.
    • Se detectan duplicados y no se importan dos veces los mismos movimientos.
  3. Respaldá: en Respaldo podés descargar una copia de seguridad (opcionalmente cifrada con AES-256-GCM) y restaurarla cuando quieras, en cualquier equipo con MoniSafe.
  4. Repasá las metas y tips de ahorro del panel principal: la app genera recomendaciones automáticas.

🔄 4 · Cómo funcionan las actualizaciones

MoniSafe consulta un servidor central una vez por día (en silencio y de forma tolerante: si no hay internet, la app sigue funcionando normal). Cuando hay una versión nueva disponible, lo ves en tres lugares:

💡 ¿No aparece el aviso recién publicado? La verificación es una vez al día. Si ya se verificó hoy antes de que se publicara la novedad, el aviso recién aparece mañana. Para forzar la consulta usá “Buscar actualizaciones” en el pie de página.

El número de versión instalado se muestra siempre en la pantalla de login y en el pie de página, así confirmás visualmente que una actualización se aplicó.

🛠️ 5 · Solución de problemas

Windows: “Falta VCRUNTIME140.dll”
Instalá el Microsoft Visual C++ Redistributable (x64). Es el único componente de sistema que requiere Windows.
Windows: la app no se desinstala del menú de programas
Ejecutá %LOCALAPPDATA%\Programs\MoniSafe\uninstall.cmd. Windows solo refresca la lista de programas al reiniciar el explorador o el equipo.
Linux: “./MoniSafe: Permission denied”
Falta el permiso de ejecución: chmod +x MoniSafe antes de ejecutarlo.
Linux: la app no abre o cae al arrancar
Verificá que PHP esté instalado y sea 8+: php -v. Si falta alguna extensión, instalala: php -m | grep -E 'pdo_sqlite|openssl|mbstring'. Revisá el log del lanzador en ~/.monisafe/launcher.log (Windows: %APPDATA%\MoniSafe\launcher.log).
El puerto del servidor local está ocupado
La app usa el puerto 8618 (por defecto). Si está ocupado, MoniSafe prueba puertos consecutivos automáticamente. Si otro programa lo bloquea de forma rara, cerrá ese programa y volvé a lanzar.
La app no funciona sin internet, ¿es normal?
No, funciona completamente offline: todos los estilos, íconos, gráficos y fuentes están incluidos dentro del paquete. Internet solo se usa (opcionalmente) para la verificación diaria de actualizaciones.

💾 6 · Dónde viven tus datos

Datos separados del programa: sobreviven actualizaciones y desinstalaciones.

ConceptoWindowsLinux
Programa / instalación%LOCALAPPDATA%\Programs\MoniSafe~/.local/share/MoniSafe
Tus datos (base de datos + clave de cifrado)%APPDATA%\MoniSafe~/.monisafe
Acceso directoEscritorio + Menú Inicio (automático)Menú de aplicaciones (.desktop)
Desinstaladoruninstall.cmd (o panel de Aplicaciones de Windows)uninstall.sh
Log del lanzador%APPDATA%\MoniSafe\launcher.log~/.monisafe/launcher.log
🔐 Clave de cifrado Tus conceptos, notas y proveedores están cifrados con AES-256-GCM. La clave maestra se guarda junto a los datos (no junto al programa) y nunca se regenera al actualizar. Si borrás esa carpeta, los datos cifrados ya no se pueden leer.