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:
```bash
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.
Consultar [Usuarios y acceso](usuarios-y-acceso.md) 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.
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](https://learn.microsoft.com/en-us/windows/wsl/networking#accessing-a-wsl-2-distribution-from-your-local-area-network-lan).
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:
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:
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.
Docker debe estar iniciado y accesible desde WSL. Comprobar el servicio sin mostrar las credenciales:
```bash
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.
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:
Hay acceso, sesiones persistentes, gestión de usuarios, compañías con personas, departamentos y sedes, inventario, recursos, puestos, perfiles y configuraciones. Inicio muestra indicadores, avisos y actividad. El [plan de desarrollo](plan-de-desarrollo.md) recoge las funciones disponibles y los pendientes; las funciones retiradas se describen en [funcionalidades archivadas](funcionalidades-archivadas.md). 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.
