Skip to content

INSTALL.md

Latest commit

 

History

History
279 lines (180 loc) · 6.31 KB

INSTALL.md

File metadata and controls

279 lines (180 loc) · 6.31 KB

Instalación de PDF Tracker (Linux y WSL)

Esta guía cubre la instalación del proyecto original en Linux o WSL, incluyendo requisitos, arranque, variables de entorno, tests y problemas habituales de instalación o del entorno.

Requisitos

Requisitos verificados en el código del proyecto:

  • Node.js con soporte para:
    • módulos ESM ("type": "module")
    • fetch global en Node
    • runner de tests nativo con node --test
  • npm
  • Un entorno donde pueda compilarse o instalarse sqlite3
  • Sistema Linux o WSL

Dependencias declaradas:

  • express
  • sqlite3

Preparación del entorno

Linux

Comprueba que tienes Node y npm:

node -v
npm -v

Si faltan, instálalos desde el gestor de paquetes de tu distribución o con tu gestor de versiones habitual.

WSL

Comprueba lo mismo dentro de tu distro WSL:

node -v
npm -v

Si vas a usar el selector nativo de PDF de Windows o la integración con Explorer, además necesitas:

  • acceso desde WSL a powershell.exe
  • acceso desde WSL a explorer.exe
  • una ruta compartida de Windows accesible, normalmente /mnt/c/...

Instalación del proyecto

cd /home/norwi/.openclaw/workspace/projects/pdf-tracker
npm install

Esto instalará las dependencias del proyecto y dejará listo el backend Express con SQLite.

Variables de entorno

El proyecto incluye un ejemplo mínimo:

cp .env.example .env

Contenido actual de .env.example:

PORT=3001

Importante: el servidor no carga .env automáticamente porque el proyecto no usa dotenv. En el estado actual del código, estas variables deben exportarse en la shell o pasarse inline al arrancar.

Ejemplo:

PORT=3001 npm start

Variables soportadas por el código

Puerto HTTP

  • PORT: puerto del servidor, por defecto 3001

Integración WSL con Windows

  • OPENCLAW_WSL_POWERSHELL: ruta a powershell.exe desde WSL
  • OPENCLAW_WSL_EXPLORER: ruta a explorer.exe desde WSL
  • OPENCLAW_WSL_PICKER_SCRIPT: ruta al script PowerShell del selector de PDF
  • OPENCLAW_WSL_PICKER_TMP_DIR: directorio temporal compartido para el resultado del selector
  • OPENCLAW_WSL_PICKER_TIMEOUT_MS: timeout del selector en milisegundos, con mínimo efectivo de 250

Valores por defecto relevantes en el código:

  • OPENCLAW_WSL_POWERSHELL=/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe
  • OPENCLAW_WSL_EXPLORER=/mnt/c/Windows/explorer.exe
  • OPENCLAW_WSL_PICKER_SCRIPT=<proyecto>/scripts/pick-pdf-windows.ps1
  • OPENCLAW_WSL_PICKER_TMP_DIR=/mnt/c/Windows/Temp
  • OPENCLAW_WSL_PICKER_TIMEOUT_MS=15000

Arranque

Arranque normal

cd /home/norwi/.openclaw/workspace/projects/pdf-tracker
npm start

Modo desarrollo

npm run dev

En este proyecto ambos scripts ejecutan actualmente el mismo comando:

node src/server.js

Verificación rápida

Una vez arrancado, abre:

  • http://localhost:3001

Y comprueba el healthcheck:

curl http://localhost:3001/health

Respuesta esperada similar a:

{"ok":true,"app":"pdf-tracker","dbPath":".../data/pdf-tracker.sqlite"}

Datos y almacenamiento

La base de datos SQLite se crea automáticamente en:

  • data/pdf-tracker.sqlite

El directorio data/ también se crea automáticamente si no existe.

Tests

Para ejecutar toda la suite:

npm test

El proyecto usa el runner nativo de Node:

node --test

Cobertura observable en los tests incluidos:

  • creación y migración de base de datos
  • API de alta, listado, filtrado, edición y borrado
  • GET /health
  • servido del frontend estático
  • parseo y deduplicación de keywords
  • normalización de rutas
  • integración de utilidades del sistema
  • selector nativo de PDF en Linux y WSL

Troubleshooting

npm install falla al instalar sqlite3

Suele ser un problema del entorno de compilación o de binarios nativos.

Qué revisar:

  • versión de Node instalada
  • que npm esté funcionando correctamente
  • que el entorno tenga herramientas básicas de compilación si el paquete necesita compilarse
  • repetir la instalación limpia:
rm -rf node_modules package-lock.json
npm install

Si estás en WSL, asegúrate de ejecutar la instalación dentro del propio entorno WSL del proyecto.

El servidor no arranca o el puerto no es el esperado

El código usa:

const PORT = process.env.PORT || 3001;

Así que debes exportar el puerto o pasarlo al arrancar:

PORT=3001 npm start

Recuerda que copiar .env no basta por sí solo en este proyecto.

La app arranca, pero no carga la interfaz

Comprueba:

  • que npm start siga en ejecución
  • que public/index.html exista
  • que puedas acceder a http://localhost:3001/health

Si /health responde pero / no, revisa el directorio public/.

No se crea la base de datos

La app intenta crear automáticamente:

  • el directorio data/
  • el fichero data/pdf-tracker.sqlite

Si falla, revisa permisos de escritura en el directorio del proyecto.

En Linux no se abre el selector nativo de PDF

En Linux el backend intenta usar, por este orden:

  • zenity
  • kdialog

Si ninguno está disponible, la app devolverá un error y tendrás que pegar la ruta manualmente.

En WSL falla el selector de PDF de Windows

Revisa:

  • que exista powershell.exe en la ruta configurada
  • que exista explorer.exe si también usas apertura de carpetas
  • que exista scripts/pick-pdf-windows.ps1
  • que /mnt/c/Windows/Temp o el directorio configurado sea accesible
  • que el timeout no sea demasiado bajo

Si aun así falla, puedes seguir usando la app escribiendo la ruta del PDF manualmente.

Abrir carpeta o mostrar fichero falla

Es normal si:

  • el registro apunta a una URL (http://, https://, file://)
  • el entorno no soporta resaltar el fichero de forma nativa
  • WSL no puede acceder a explorer.exe

En Linux, la app puede degradar la acción y abrir solo la carpeta contenedora.

Estoy en WSL y quiero usar rutas de Windows

La app tolera rutas como:

  • D:\Papers\paper.pdf
  • /mnt/d/Papers/paper.pdf

Para integración con Windows, el código convierte rutas /mnt/<unidad>/... a formato Windows cuando es posible.

Resumen rápido

cd /home/norwi/.openclaw/workspace/projects/pdf-tracker
npm install
PORT=3001 npm start
npm test

Después abre http://localhost:3001.