Instalar y Configurar Papernook - Guía Oficial Verificada
Biblioteca académica auto-alojada filesystem-first para captura, anotación y lectura con IA privada
¿Qué es Papernook?
Papernook es una biblioteca de documentos académicos auto-alojada que prioriza el sistema de archivos como fuente de verdad. Permite capturar PDFs desde arXiv y editoriales mediante extensiones oficiales para Safari (Mac App Store) y Chrome Web Store, anotar directamente en los PDFs con Apple Pencil o ratón, y consultar con IA configurable (Claude Code, Codex, API local).
La arquitectura combina Next.js con Python/Node.js, usando SQLite FTS5 como acelerador de búsqueda reconstruible. Las anotaciones se escriben directamente en los PDFs para máxima portabilidad, las conversaciones se almacenan como archivos JSONL simples, y el índice puede eliminarse sin perder la biblioteca.
Prerrequisitos del Sistema
| Requisito | Detalles | Verificación |
|---|---|---|
| Sistema Operativo | Linux, macOS o Windows con WSL2 | N/A |
| Puerto 3000 | Libre y accesible en localhost | netstat -tlnp | grep 3000 |
| Herramientas CLI | Curl, Git, Node.js (v18+), Python (v3.9+) | curl --version && git --version && node --version && python --version |
| Proveedor de IA | Claude Code CLI, Codex CLI o API OpenAI-compatible | claude --version || codex --version |
| Docker (opcional) | Para despliegue containerizado | docker --version |
Métodos de Instalación
Método 1: Script Oficial (Recomendado)
Instalación rápida que clona el repo, detecta Codex/Claude automáticamente y escribe .env.
Paso 1: Ejecutar script
curl -fsSL https://raw.githubusercontent.com/affromero/papernook/main/scripts/install.sh | bash
Paso 2: Instalación reproducible (opcional)
git clone --branch v0.3.0 --depth 1 https://github.com/affromero/papernook.git
cd papernook
./scripts/install.sh
Método 2: Docker Compose
Para despliegues multi-contenedor con mounts de credenciales.
Paso 1: Crear docker-compose.yml
version: '3.8'
services:
papernook:
image: affromero/papernook:v0.3.0
ports:
- "3000:3000"
volumes:
- ./data:/app/data
- ./CODEX_AUTH_FILE:/app/auth/codex.json
- ./CLAUDE_AUTH_FILE:/app/auth/claude.json
environment:
- NODE_ENV=productionPaso 2: Levantar servicio
docker compose up -d
Método 3: Actualización
Para actualizar una instalación existente.
Paso 1: Actualizar
papernook update
Paso 2: Revisar qué cambiaría
papernook update --check
Paso 3: Seguir main (desarrollo)
papernook update --main
Configuración Inicial (.env)
Variables de Entorno Esenciales
# Archivo de credenciales del proveedor de IA (obligatorio)
CODEX_AUTH_FILE=/path/to/codex.json
# O alternativamente:
CLAUDE_AUTH_FILE=/path/to/claude.json
# Puerto del servidor (por defecto: 3000)
PORT=3000
# WebDAV opcional para sincronización multi-dispositivo
WEBDAV_ENABLED=false
WEBDAV_HOST=
WEBDAV_PORT=5180
# Configuración de seguridad
NODE_ENV=productionNota: El script install.sh detecta automáticamente Codex/Claude y escribe .env. Verificar que las herramientas CLI estén disponibles antes de iniciar.
Verificación de Funcionamiento
Chequeo Post-Instalación
- Verificar puerto 3000:
netstat -tlnp | grep 3000 - Acceso web: Navegar a
http://localhost:3000 - Estado del servicio:
papernook status - Verificar logs:
tail -f logs/*.log
Backup, Actualización y Rollback
papernook update respalda automáticamente la biblioteca con scripts/backup.sh antes de actualizar.
Procedimiento de Actualización Segura
- Verificar estado actual:
papernook status - Ejecutar actualización:
papernook update - Verificar salud:
papernook update --check - Reconstruir índice si es necesario: El sistema reconstruye SQLite FTS5 desde archivos automáticamente
Rollback Manual (si es necesario)
# Restaurar desde backup automático
cd scripts/backup.sh
./restore.sh <version_tag>Errores Habituales y Soluciones
| Error | Causa Probable | Solución Verificada |
|---|---|---|
Port 3000 already in use |
Puerto ocupado por otro proceso | lsof -i :3000 → matar proceso o cambiar PORT en .env |
Claude/Codex not detected |
Herramientas CLI no instaladas | Instalar: npm install -g @anthropics/claude-code o usar API externa |
SQLite index corrupted |
Corrupción del índice FTS5 | Borrar carpeta de índice y reconstruir: papernook update --check |
Docker volume permission denied |
Problemas de permisos en mounts | chmod -R 755 ./data o usar user:group correctos en docker-compose.yml |
Seguridad
- Licencia MIT: Código abierto y modificable
- CI automatizado: GitHub Actions con CodeQL y gitleaks
- Dependabot: Actualización automática de dependencias
- .gitleaks.toml: Protección contra fugas de secretos
- Secrets management: .env.example con mounts por proveedor (nunca commitar credenciales)
Preguntas Frecuentes
- ¿Puedo eliminar el índice SQLite sin perder mis documentos?
- Sí. El filesystem es la fuente de verdad; borrar el índice y reconstruirlo desde los archivos no afecta a PDFs ni anotaciones.
- ¿Cómo actualizo Papernook?
- Ejecutar
papernook update(respalda automáticamente con scripts/backup.sh). Para desarrollo:papernook update --main. Verificarpapernook statusantes de actualizar. - ¿Necesito Docker para usarlo?
- No. El script install.sh detecta Codex/Claude, escribe .env y levanta el servicio. Docker Compose es opcional para despliegues multi-contenedor.
- ¿Puedo cambiar de proveedor de IA?
- Sí. Configurar CLAUDE_AUTH_FILE o CODEX_AUTH_FILE en .env, apuntando a API local, Claude Code CLI, Codex CLI o cualquier servidor OpenAI-compatible.
- ¿Cómo sincronizo entre dispositivos?
- Opcional: configurar WebDAV para acceso multi-dispositivo. Las anotaciones en PDFs son portables sin sincronización adicional.