5.7 KiB
Puesta en marcha
Entorno
El repositorio está en /home/david/dev/metis-desk, dentro de WSL2 Ubuntu-24.04. Necesita Node.js 24.x, PNPM 11.25.0 y Docker disponible desde WSL. No depende de paquetes locales de factuges-erp.
Desde una terminal Ubuntu-24.04:
cd /home/david/dev/metis-desk
pnpm install --frozen-lockfile
pnpm db:up
pnpm dev
pnpm db:up genera .env con secretos locales si no existe e inicia MariaDB en un volumen persistente. No crea usuarios de la aplicación. El servidor aplica las migraciones al arrancar.
Abrir http://localhost:5173. La primera apertura permite crear el administrador inicial; las siguientes muestran el acceso. La API escucha en 127.0.0.1:3001 y la base de datos en 127.0.0.1:3307.
Una vez autenticado, Inicio utiliza /dashboard y cada sección tiene URL propia.
Se pueden abrir o recargar directamente /tickets, /catalogs o
/companies/:companyId. Consultar Rutas del cliente para
las fichas, los filtros y el requisito de fallback de la SPA en producción.
Consultar Usuarios y acceso para la configuración inicial y protección de cuentas. No borrar el volumen para actualizar o reiniciar: contiene usuarios, compañías, contactos y sedes.
Si se cambia PORT, configurar API_PROXY_TARGET al arrancar Vite (por defecto http://127.0.0.1:3001). Si cambia el origen del navegador, actualizar APP_ORIGIN en .env.
Acceso desde la red local
La dirección de acceso es http://192.168.0.2:5173. Vite escucha en la red de WSL y redirige /api a la API interna. En WSL2 con NAT se necesita además reenviar el puerto desde Windows, siguiendo el procedimiento de Microsoft.
El script versionado scripts/enable-lan-access.ps1 detecta la IPv4 de eth0 en Ubuntu-24.04, comprueba que Vite responde, configura el reenvío TCP y crea una regla de firewall para el perfil privado y la subred local. La interfaz de Windows con IP 192.168.0.2 debe tener perfil Privado. Mantener pnpm dev ejecutándose en WSL.
Copiar el script a una carpeta de Windows y ejecutarlo desde PowerShell como administrador, en esa carpeta:
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\enable-lan-access.ps1
La excepción de ejecución solo afecta a ese proceso. Se pueden indicar -Distribution, -ListenAddress y -Port si cambian los valores. Comprobar el puerto anunciado por Vite: si 5173 está ocupado, puede usar otro.
En .env, establecer APP_ORIGIN=http://192.168.0.2:5173 y reiniciar pnpm dev para permitir guardar datos desde la dirección LAN. Solo se admite un origen: con esa configuración, las operaciones desde localhost serán rechazadas. No se publican el puerto de la API ni el de MariaDB.
Volver a ejecutar el script después de un cambio de IP de WSL. El script actualiza el destino del mismo reenvío. Si cambia la IP de Windows o el puerto, retirar primero las reglas anteriores y actualizar también APP_ORIGIN.
Para retirar el acceso con los valores predeterminados, ejecutar en PowerShell como administrador:
netsh interface portproxy delete v4tov4 listenaddress=192.168.0.2 listenport=5173 protocol=tcp
Remove-NetFirewallRule -Name 'MetisDesk-WSL-LAN-192.168.0.2-5173'
El script reinicia IP Helper (iphlpsvc) después de configurar las reglas para que aplique el reenvío; esto interrumpe brevemente otros reenvíos gestionados por ese servicio. Espera hasta diez segundos a que aparezca el listener IPv4 y comprueba una respuesta HTTP 200 a través de la IP de Windows, sin usar el proxy del sistema, antes de anunciar éxito. Si falla, muestra los reenvíos y los listeners y conserva las reglas para diagnóstico. Esta comprobación local no garantiza acceso desde otro dispositivo: verificarlo también desde la red local. El reinicio manual del servicio resolvió el fallo observado; el script actualizado queda pendiente de ejecución en Windows.
Diagnóstico de conexión con MariaDB
Docker debe estar iniciado y accesible desde WSL. Comprobar el servicio sin mostrar las credenciales:
docker compose ps -a
docker compose logs --tail=50 database
pnpm db:up
pnpm db:up espera a que MariaDB esté saludable antes de terminar y conserva el volumen existente. El contenedor utiliza restart: unless-stopped: vuelve a arrancar tras reiniciar Docker o ante una salida inesperada, salvo que se haya detenido explícitamente. Si se usa docker compose stop o down, es necesario ejecutar de nuevo pnpm db:up. Nunca usar down -v para resolver una conexión: elimina los datos.
El backend ejecutado en WSL conecta a 127.0.0.1:3307; el puerto interno del contenedor es 3306. Después de recuperar la base de datos, reiniciar el backend si había terminado con un error de arranque: el modo watch espera cambios en archivos y no se reactiva por arrancar Docker.
Verificaciones
pnpm typecheck
pnpm lint
pnpm test
pnpm check
pnpm build
La base local debe estar encendida para las pruebas de integración. Estas solo usan metis_desk_test. La compilación genera apps/server/dist y apps/web/dist.
Para ejecutar la API compilada, parar primero el servidor de desarrollo:
pnpm --filter @metis/server start
Alcance
Hay acceso, sesiones persistentes, gestión de usuarios, compañías clientes con contactos y sedes y una página inicial que comprueba la conexión. Inventario y tickets siguen pendientes. Las tablas nuevas se crean al arrancar la API mediante migraciones explícitas.
La API compilada todavía no sirve la interfaz estática. El despliegue, proxy HTTPS, backups y recuperación de acceso se definirán en una entrega posterior.