Instalación · 5 min read · Sep 25, 2025

Cómo instalar Paperless con Nginx en Debian

Paperless es una aplicación de Python que ingiere documentos escaneados, los indexa y los presenta en una interfaz web fácil de usar. En este tutorial, instalaremos Paperless con un proxy inverso HTTPS de Nginx en Debian 10.

  • Un sistema Debian 10 en el que tengas acceso root.
  • Un nombre de dominio registrado que apunte a tu servidor.

Todos los comandos mostrados en este documento deben ser ejecutados como root, a menos que se indique lo contrario.

Establece la variable de entorno $VISUAL a un editor de texto de tu elección. Por ejemplo, para usar nano:

echo "export VISUAL=nano" >> ~/.bashrc
. ~/.bashrc

Paperless requiere varios componentes de software para su instalación y funcionamiento. Instálalos de la siguiente manera:

apt update
apt install -y gnupg2 python3 python3-dev python3-pip python3-virtualenv tesseract-ocr tesseract-ocr-eng unpaper imagemagick libpoppler-cpp-dev optipng git gcc g++

Si vas a trabajar con documentos en idiomas distintos al inglés, instala los archivos de idioma de Tesseract correspondientes. Por ejemplo, para francés y español:

apt install -y tesseract-ocr-fra tesseract-ocr-spa

Puedes listar todos los paquetes de tesseract disponibles usando:

apt list tesseract-ocr-*

Si no estás seguro de qué código de 3 letras corresponde al idioma deseado, consulta esta Lista de Códigos ISO 639-2.

Si bien es posible ejecutar paperless como root, se recomienda encarecidamente usar un usuario con bajos privilegios y con el inicio de sesión deshabilitado. Crea un usuario y un grupo llamados paperless:

useradd -d /opt/paperless -M -r -s /bin/bash -U -p x paperless

Clona el repositorio de Github de Paperless en /opt/paperless

git clone https://github.com/the-paperless-project/paperless.git /opt/paperless

Dale al usuario paperless la propiedad de ese directorio:

chown -R paperless:paperless /opt/paperless

Copia el ejemplo de configuración incluido como punto de partida:

cp /opt/paperless/paperless.conf.example /etc/paperless.conf

Y ábrelo en tu editor de texto:

$VISUAL /etc/paperless.conf

Elige un directorio desde el cual Paperless ingiera documentos escaneados y establece el parámetro PAPERLESS_CONSUMPTION_DIR en consecuencia:

PAPERLESS_CONSUMPTION_DIR="/opt/paperless/paper_in"

Encuentra, descomenta (eliminando el carácter #) y cambia los valores de las siguientes líneas a algo seguro:

#PAPERLESS_PASSPHRASE="secret"
#PAPERLESS_SECRET_KEY="change-me"

Si tu escáner admite el envío de documentos escaneados por correo electrónico, puedes hacer que paperless los ingiera automáticamente desde la bandeja de entrada receptora. Para habilitar esta función, establece las opciones PAPERLESSCONSUME_MAIL*. Por razones de seguridad, se recomienda crear una cuenta de correo dedicada a Paperless. Por ejemplo:

PAPERLESS_CONSUME_MAIL_HOST="imap.example.com"
PAPERLESS_CONSUME_MAIL_PORT="993"
PAPERLESS_CONSUME_MAIL_USER="[email protected]"
PAPERLESS_CONSUME_MAIL_PASS="imap_password"

Guarda tus cambios y sal, luego cambia el propietario de este archivo a paperless y ajusta sus permisos:

chown paperless:paperless /etc/paperless.conf
chmod 0400 /etc/paperless.conf

Cambia al usuario paperless:

su - paperless

Crea el directorio de consumo:

mkdir /opt/paperless/paper_in

Crea un entorno virtual de Python. Esto proporcionará un entorno estable y aislado donde podemos instalar los módulos y versiones específicas de Python requeridos por Paperless.

python3 -m virtualenv --python=/usr/bin/python3 venv

Actívalo:

. venv/bin/activate

Instala los módulos de Python requeridos por paperless:

pip3 install -r requirements.txt

Este comando puede tardar un tiempo. Una vez que termine, ejecuta los siguientes comandos para inicializar la base de datos y crear los archivos estáticos para el servicio web:

cd src/
./manage.py migrate
./manage.py collectstatic

Crea credenciales de inicio de sesión para la cuenta de administrador de la interfaz web ejecutando el siguiente comando y respondiendo a las indicaciones:

./manage.py createsuperuser

Antes de configurar un servidor web adecuado y servicios systemd, intentaremos ejecutar paperless manualmente. En este punto, aún deberías estar conectado como paperless en el entorno virtual de Python.

Inicia el servidor web y el consumidor de documentos en segundo plano:

./manage.py runserver 0.0.0.0:8000 &
./manage.py document_consumer &

Coloca cualquier documento escaneado en el directorio de consumo configurado en el Paso 3. Por ejemplo:

wget https://i.imgur.com/DPr5wWG.jpg -O /opt/paperless/paper_in/test1.jpg

Navega a http://IP_or_DOMAIN:8000/ e inicia sesión con las credenciales elegidas en el Paso 3. En el menú “DOCUMENTOS”, haz clic en “Documentos” para ver la lista de documentos. En unos minutos, el documento escaneado debería ser procesado y estar disponible.

Detén paperless antes de proceder al siguiente paso:

pkill -f manage.py

Crearemos archivos de unidad systemd para poder gestionar adecuadamente los servicios web y de consumidor. Sal de nuevo a tu shell root:

exit

Crea un archivo de unidad para el servicio web:

$VISUAL /etc/systemd/system/paperless-webserver.service

Y escribe lo siguiente:

[Unit]
Description=Servidor Web Gunicorn de Paperless
Requires=network.target
[Service]
User=paperless
Group=paperless
ExecStart=/opt/paperless/venv/bin/gunicorn --pythonpath=/opt/paperless/src paperless.wsgi -w 3 -b 127.0.0.1:8000
Restart=on-failure
[Install]
WantedBy=multi-user.target

NOTA: Es posible que desees modificar el número de procesos de trabajo en el comando ExecStart. El servicio que se muestra aquí inicia Gunicorn con 3 trabajadores ( -w 3).

A continuación, crea otro archivo de unidad para el proceso del consumidor de documentos:

$VISUAL /etc/systemd/system/paperless-consumer.service

Y escribe lo siguiente:

[Unit]
Description=Consumidor de Documentos Paperless
Requires=network.target
[Service]
User=paperless
Group=paperless
ExecStart=/opt/paperless/venv/bin/python3 /opt/paperless/src/manage.py document_consumer
Restart=on-failure
[Install]
WantedBy=multi-user.target

Inicia estos servicios:

systemctl daemon-reload
systemctl start paperless-webserver.service paperless-consumer.service

Asegúrate de que ambos estén en funcionamiento:

systemctl status paperless-webserver.service paperless-consumer.service

Si deseas que paperless se inicie automáticamente al arrancar el sistema, ejecuta el comando:

systemctl enable paperless-webserver.service paperless-consumer.service

Instala Nginx y certbot:

apt update
apt install -y nginx certbot

Asegúrate de que Nginx esté habilitado y en funcionamiento:

systemctl enable --now nginx.service

Obtén un certificado de Let’s Encrypt para tu dominio con certbot:

certbot certonly --webroot --webroot-path /var/www/html -d your_domain

Desactiva el archivo de configuración predeterminado de Nginx y abre uno nuevo:

rm /etc/nginx/sites-enabled/default
$VISUAL /etc/nginx/sites-available/paperless

Ingresa lo siguiente, reemplaza your_domain con tu nombre de dominio:

server {
    listen 80;
    server_name your_domain;
    return 301 https://$server_name$request_uri;
    access_log /var/log/nginx/paperless_access.log;
    error_log /var/log/nginx/paperless_error.log;
}
server {
    listen 443 ssl;
    server_name your_domain;
    index index.html index.htm index.php;
    access_log /var/log/nginx/paperless_access.log;
    error_log /var/log/nginx/paperless_error.log;
    ssl on;
    ssl_certificate /etc/letsencrypt/live/your_domain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your_domain/privkey.pem;
    location /static {
        autoindex on;
        alias /opt/paperless/static;
    }
    location / {
        proxy_set_header Host $http_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;
        proxy_pass http://127.0.0.1:8000;
    }
}

Habilita esta configuración vinculándola en el directorio de Nginx sites-enabled y verifica si hay errores:

ln -s /etc/nginx/sites-available/paperless /etc/nginx/sites-enabled
nginx -t

Luego carga los cambios:

systemctl reload nginx.service

Tu instancia de Paperless debería ser ahora accesible en https://your_domain.

Dado que el usuario del sistema paperless no necesita acceso a un shell funcional después de la configuración inicial, podemos cambiarlo a /usr/sbin/nologin:

usermod -s /usr/sbin/nologin paperless

Si el servidor web Gunicorn no se inicia con el mensaje de error [ERROR] Connection in use, verifica si hay procesos ya vinculados al puerto 8000/tcp:

ss -lntp

Mata/desactiva el proceso problemático si es necesario, o modifica /etc/systemd/system/paperless-webserver.service y /etc/nginx/sites-enabled/paperless para usar otro puerto de red para Gunicorn.

Share: X/Twitter LinkedIn
#Instalación

Recibe nuevas publicaciones en tu bandeja de entrada.

No spam. Cancela la suscripción en cualquier momento.