--- title: "Cómo instalar Paperless-ngx con Docker en Ubuntu 24.04" description: "Instala Paperless-ngx con Docker Compose, PostgreSQL y Tika en Ubuntu 24.04, configura el OCR en español, publícalo por HTTPS y programa copias de seguridad." category: "Productividad Self-Hosted" language: es source: https://cubepath.com/es/docs/productividad-self-hosted/paperless-ngx-gestion-de-documentos updated: 2026-09-25 --- # Cómo instalar Paperless-ngx con Docker en Ubuntu 24.04 Paperless-ngx es un gestor documental autoalojado que convierte tus escaneos y PDF en un archivo con búsqueda de texto completo. Cada documento que recibe pasa por OCR, se archiva en PDF/A y se clasifica automáticamente con etiquetas, remitentes y tipos de documento que aprende de tus propias asignaciones. En este tutorial instalarás Paperless-ngx con Docker Compose, PostgreSQL, Tika y Gotenberg en Ubuntu 24.04, configurarás el OCR en español, lo publicarás por HTTPS con Nginx y programarás exportaciones de respaldo. ## Requisitos previos - Un servidor con Ubuntu 24.04 LTS con al menos 2 núcleos y 4 GB de RAM, por ejemplo un VPS de CubePath. El OCR es intensivo en CPU; más núcleos procesan los documentos más rápido. - Un usuario no root con privilegios `sudo`. - Docker Engine y el plugin de Docker Compose instalados desde el repositorio oficial de Docker. - Un dominio con un registro A apuntando a la IP del servidor, por ejemplo `docs.tu_dominio`. ## Paso 1: Descargar los ficheros de Compose oficiales El proyecto mantiene varias variantes de `docker-compose.yml` en su repositorio. La variante `postgres-tika` incluye PostgreSQL como base de datos y los servicios Tika y Gotenberg, que permiten procesar también documentos de Office (`.docx`, `.xlsx`, `.odt`) y correos `.eml`. ```bash mkdir -p ~/paperless-ngx cd ~/paperless-ngx wget -O docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres-tika.yml wget -O docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env wget -O .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env ``` - `docker-compose.yml` define los servicios: `broker` (Redis), `db` (PostgreSQL), `webserver` (Paperless-ngx), `gotenberg` y `tika`. - `docker-compose.env` contiene la configuración de Paperless-ngx. - `.env` fija el nombre del proyecto de Compose (`paperless`). Crea las carpetas que el fichero de Compose monta desde el host: `consume` es la bandeja de entrada de documentos y `export` es el destino de las copias de seguridad: ```bash mkdir -p ~/paperless-ngx/{consume,export} ``` ## Paso 2: Configurar Paperless-ngx Paperless-ngx necesita una clave secreta para firmar las sesiones. Genérala: ```bash openssl rand -hex 32 ``` Averigua también tu UID y GID, para que los ficheros que Paperless-ngx cree en `consume` y `export` pertenezcan a tu usuario: ```bash id -u; id -g ``` ```output 1000 1000 ``` Edita la configuración: ```bash nano ~/paperless-ngx/docker-compose.env ``` Descomenta (quitando el `#`) y ajusta estas variables. Deja el resto como está: ```ini USERMAP_UID=1000 USERMAP_GID=1000 PAPERLESS_URL=https://docs.tu_dominio PAPERLESS_SECRET_KEY=clave_generada_con_openssl PAPERLESS_TIME_ZONE=Europe/Madrid # Idiomas del OCR: español e inglés PAPERLESS_OCR_LANGUAGE=spa+eng ``` `PAPERLESS_URL` es obligatorio cuando Paperless-ngx está detrás de un proxy con HTTPS: se usa para la protección CSRF y para los enlaces que genera. La imagen de Docker ya incluye los paquetes de OCR de inglés, alemán, italiano, español y francés; para otros idiomas añade sus códigos de Tesseract a `PAPERLESS_OCR_LANGUAGES` (en plural), por ejemplo `PAPERLESS_OCR_LANGUAGES=por cat`. Protege el fichero: ```bash chmod 600 ~/paperless-ngx/docker-compose.env ``` ## Paso 3: Limitar el puerto a localhost El servicio `webserver` publica el puerto 8000 en todas las interfaces. Docker gestiona sus propias reglas de iptables, de modo que el puerto quedaría accesible desde internet aunque UFW no lo permita. Nginx será la única entrada, así que publícalo solo en `127.0.0.1`: ```bash nano ~/paperless-ngx/docker-compose.yml ``` En el servicio `webserver`, cambia `ports` para que quede así: ```yaml ports: - "127.0.0.1:8000:8000" ``` ## Paso 4: Arrancar los servicios y crear el administrador Descarga las imágenes y arranca todo en segundo plano: ```bash cd ~/paperless-ngx docker compose pull docker compose up -d ``` El primer arranque aplica las migraciones de la base de datos y tarda uno o dos minutos. Comprueba el estado: ```bash docker compose ps --format "table {{.Service}}\t{{.Status}}" ``` ```output SERVICE STATUS broker Up 2 minutes db Up 2 minutes gotenberg Up 2 minutes tika Up 2 minutes webserver Up 2 minutes (healthy) ``` Crea el usuario administrador. El comando te pedirá nombre, correo y contraseña: ```bash docker compose run --rm webserver createsuperuser ``` Comprueba que la aplicación responde en local: ```bash curl -s -o /dev/null -w "%{http_code}\n" -L http://127.0.0.1:8000/ ``` ```output 200 ``` ## Paso 5: Publicar Paperless-ngx por HTTPS con Nginx Instala Nginx y Certbot, y abre los puertos web en UFW: ```bash sudo apt install nginx certbot python3-certbot-nginx sudo ufw allow OpenSSH sudo ufw allow "Nginx Full" sudo ufw enable ``` Crea el sitio: ```bash sudo nano /etc/nginx/sites-available/paperless ``` ```nginx server { listen 80; listen [::]:80; server_name docs.tu_dominio; # Tamaño máximo de los documentos subidos desde la web client_max_body_size 100M; location / { proxy_pass http://127.0.0.1:8000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket para el estado de procesamiento en tiempo real proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_redirect off; proxy_read_timeout 300s; } } ``` Activa el sitio, valida la configuración y obtén el certificado: ```bash sudo ln -s /etc/nginx/sites-available/paperless /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx sudo certbot --nginx -d docs.tu_dominio ``` Abre `https://docs.tu_dominio` e inicia sesión con el administrador. Si ves un error `CSRF verification failed`, revisa que `PAPERLESS_URL` coincide exactamente con la URL del navegador y ejecuta `docker compose up -d` para aplicar el cambio. ## Paso 6: Añadir documentos Hay tres formas habituales de introducir documentos: - **Desde la web**: arrastra PDF o imágenes al panel principal. - **Carpeta de consumo**: cualquier fichero que copies en `~/paperless-ngx/consume` se procesa y después se elimina de la carpeta. - **Correo**: Paperless-ngx puede leer una cuenta IMAP y procesar los adjuntos (paso 8). Prueba la carpeta de consumo con un PDF escaneado: ```bash cp factura-enero.pdf ~/paperless-ngx/consume/ ``` Sigue el procesamiento en el log: ```bash cd ~/paperless-ngx docker compose logs -f webserver ``` Cuando termine verás una línea similar a `Document factura-enero consumption finished` y el fichero desaparecerá de `consume`. Pulsa `Ctrl+C` para salir del log. En la web, abre el documento y la pestaña **Contenido**: debe mostrar el texto extraído por OCR. Desde tu equipo puedes enviar documentos directamente a la carpeta de consumo por SSH: ```bash scp *.pdf tu_usuario@ip_del_servidor:~/paperless-ngx/consume/ ``` ## Paso 7: Organizar con etiquetas, remitentes y flujos de trabajo Paperless-ngx organiza los documentos con tres conceptos: | Concepto | Para qué sirve | Ejemplos | |---|---|---| | Etiquetas | Clasificación libre, varias por documento | Impuestos, Hogar, Coche | | Remitentes | Quién emite el documento | Compañía eléctrica, Banco, Gestoría | | Tipos de documento | Qué es el documento | Factura, Contrato, Nómina | Créalos en el menú lateral. Para cada uno puedes elegir un algoritmo de asignación: **Auto** aprende de los documentos que ya has clasificado a mano, mientras que **Cualquier palabra**, **Todas las palabras**, **Coincidencia exacta** o **Expresión regular** aplican reglas fijas sobre el texto del documento. Con unas decenas de documentos clasificados, el modo Auto acierta en la mayoría de los casos. Para acciones más complejas, usa **Flujos de trabajo**: por ejemplo, un disparador "Documento añadido" con filtro de nombre `*nomina*` que asigne el tipo Nómina, la etiqueta Trabajo y un propietario concreto. La búsqueda de texto completo está en la barra superior. Además de palabras sueltas, admite filtros como `tag:impuestos`, `correspondent:banco`, `type:factura` o rangos de fechas como `created:[2024 to 2025]`. ## Paso 8: Importar documentos desde el correo Para que las facturas que recibes por correo lleguen solas, ve a **Correo** en el menú lateral y añade una cuenta IMAP con el servidor, el puerto (993 con SSL), el usuario y la contraseña. Muchos proveedores, como Gmail, requieren una contraseña de aplicación en lugar de la contraseña normal. Después crea una **Regla de correo** para esa cuenta, por ejemplo: - Carpeta: `INBOX`. - Filtro de asunto: `factura`. - Acción: procesar los adjuntos y mover el correo a la carpeta `Procesados`. - Asignar la etiqueta `Facturas`. Paperless-ngx revisa las cuentas cada 10 minutos. Puedes comprobar el resultado en **Registros** (sección `mail`). ## Paso 9: Programar copias de seguridad La herramienta `document_exporter` vuelca todos los documentos (originales y versiones archivadas) junto con sus metadatos a la carpeta `export` en un formato que se puede importar en cualquier instalación nueva. Ejecútala a mano para probarla: ```bash cd ~/paperless-ngx docker compose exec -T webserver document_exporter ../export ``` Comprueba el resultado: ```bash ls ~/paperless-ngx/export | head ``` Deberías ver el fichero `manifest.json` y los documentos exportados. Las siguientes ejecuciones solo copian lo que ha cambiado. Programa la exportación cada noche con cron: ```bash crontab -e ``` ```text 0 2 * * * cd "$HOME/paperless-ngx" && docker compose exec -T webserver document_exporter ../export > /dev/null 2>&1 ``` Después, copia `~/paperless-ngx/export` fuera del servidor con `restic`, `borg` o `rsync`. Para restaurar en una instalación limpia, copia la exportación a `export` y ejecuta `docker compose exec -T webserver document_importer ../export`. ## Actualizar Paperless-ngx Haz una exportación (paso 9) y actualiza las imágenes: ```bash cd ~/paperless-ngx docker compose pull docker compose up -d ``` Las migraciones de base de datos se aplican automáticamente al arrancar. Las actualizaciones a una versión mayor de PostgreSQL requieren un volcado y restauración manual; revisa las notas de la versión antes de cambiar la imagen de `db`. ## Solución de problemas **Los documentos se quedan en `consume` y no se procesan.** Revisa `docker compose logs webserver --tail 50`. Si ves errores de permisos, comprueba que `USERMAP_UID` y `USERMAP_GID` coinciden con el propietario de la carpeta (`ls -ln ~/paperless-ngx`). **El OCR no reconoce bien los acentos o la ñ.** Comprueba que el idioma está disponible y configurado: ```bash docker compose exec webserver tesseract --list-langs ``` La lista debe incluir `spa`. Si no aparece el idioma que necesitas, añádelo a `PAPERLESS_OCR_LANGUAGES` y recrea el contenedor. Escanea a 300 ppp para mejores resultados. **Error `CSRF verification failed` al iniciar sesión.** `PAPERLESS_URL` no coincide con la URL real (esquema, dominio y puerto). Corrígelo en `docker-compose.env` y ejecuta `docker compose up -d`. **Los documentos de Office no se procesan.** Asegúrate de estar usando la variante `postgres-tika` y de que los contenedores `tika` y `gotenberg` están en marcha con `docker compose ps`. ## Conclusión Tienes Paperless-ngx funcionando con PostgreSQL, Tika y Gotenberg, publicado por HTTPS con Nginx, con OCR en español, importación desde el correo y exportaciones nocturnas. Como siguientes pasos puedes activar la autenticación en dos pasos en tu perfil, crear usuarios con permisos por documento para compartir el archivo con tu familia o equipo, o usar una app móvil compatible para escanear directamente al servidor.