Cómo autoalojar Paperclip en un VPS (Guía paso a paso 2026)

Cómo autoalojar Paperclip en un VPS (Guía paso a paso 2026)

Paperclip es uno de los sistemas de gestión documental autoalojados más limpios disponibles. Funciona como un único contenedor Docker, almacena archivos en un volumen local y expone una interfaz web en el puerto 8080. Esta guía te lleva por una instalación completa lista para producción en un VPS Linux — desde el aprovisionamiento del servidor hasta la primera carga de documentos.

Prerequisitos

• Un VPS con Ubuntu 22.04 LTS o Debian 12 (recomendado)
• Al menos 1 vCPU, 1 GB de RAM, 20 GB de almacenamiento (2 GB de RAM recomendados para OCR)
• Acceso root o sudo vía SSH
• Un dominio o subdominio apuntando a la IP del VPS (opcional pero recomendado para HTTPS)

Opciones VPS recomendadas:

• Hetzner Cloud CX22 — 4,15 €/mes, 2 vCPU, 4 GB de RAM, 40 GB NVMe
• Contabo VPS S — 5,99 €/mes, 4 vCPU, 8 GB de RAM, 200 GB NVMe

Paso 1: Actualizar el servidor

apt update && apt upgrade -y

Paso 2: Instalar Docker

curl -fsSL https://get.docker.com | sh
systemctl enable docker
systemctl start docker

Verificar que Docker está funcionando:

docker --version

Paso 3: Instalar Docker Compose

apt install docker-compose-plugin -y
docker compose version

Paso 4: Crear un directorio de trabajo

mkdir -p /opt/paperclip && cd /opt/paperclip

Paso 5: Crear un docker-compose.yml

nano /opt/paperclip/docker-compose.yml

Pega la siguiente configuración:

version: "3.8"

services:
  paperclip:
    image: paperclip/paperclip:latest
    container_name: paperclip
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - paperclip_data:/data
    environment:
      - PAPERCLIP_SECRET_KEY=cambia_esto_por_una_clave_aleatoria
      - PAPERCLIP_OCR_ENABLED=true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  paperclip_data:

Importante: reemplaza cambia_esto_por_una_clave_aleatoria con una cadena aleatoria. Genera una con:

openssl rand -hex 32

Paso 6: (Opcional) Usar PostgreSQL en lugar de SQLite

Para uso multiusuario o en producción, amplía el archivo compose:

version: "3.8"

services:
  db:
    image: postgres:16-alpine
    container_name: paperclip_db
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperclip
      POSTGRES_USER: paperclip
      POSTGRES_PASSWORD: contrasena_fuerte
    volumes:
      - pg_data:/var/lib/postgresql/data

  paperclip:
    image: paperclip/paperclip:latest
    container_name: paperclip
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "8080:8080"
    volumes:
      - paperclip_data:/data
    environment:
      - PAPERCLIP_SECRET_KEY=tu_clave_aleatoria
      - PAPERCLIP_DB_HOST=db
      - PAPERCLIP_DB_NAME=paperclip
      - PAPERCLIP_DB_USER=paperclip
      - PAPERCLIP_DB_PASSWORD=contrasena_fuerte
      - PAPERCLIP_OCR_ENABLED=true

volumes:
  paperclip_data:
  pg_data:

Paso 7: Iniciar Paperclip

cd /opt/paperclip
docker compose up -d

Comprobar que el contenedor ha iniciado:

docker compose ps
docker compose logs -f paperclip

Paso 8: Configurar el cortafuegos

ufw allow OpenSSH
ufw allow 80
ufw allow 443
ufw enable

Nota: el puerto 8080 no se expone directamente — el tráfico pasará a través de Caddy/Nginx con HTTPS.

Paso 9: Configurar HTTPS con Caddy

apt install caddy -y

Editar el Caddyfile:

nano /etc/caddy/Caddyfile

docs.tudominio.es {
    reverse_proxy localhost:8080
}

Recargar Caddy:

systemctl reload caddy

Caddy provisiona automáticamente un certificado Let’s Encrypt.

Paso 10: Primer inicio de sesión

1. Abre https://docs.tudominio.es (o http://TU_IP_VPS:8080 sin dominio)
2. Completa el asistente de configuración inicial — establece tu email y contraseña de administrador
3. Sube tu primer documento
4. Activa OCR si necesitas búsqueda de texto completo en archivos escaneados

Paso 11: Configurar copias de seguridad

Haz copia de seguridad del volumen Docker en local o en un bucket compatible S3:

# Copia de seguridad en archivo local
docker run --rm \
  -v paperclip_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/paperclip-backup-$(date +%Y%m%d).tar.gz /data

Programar con cron:

crontab -e
# Añadir:
0 3 * * * /opt/paperclip/backup.sh

Solución de problemas

Para recomendaciones de proveedores VPS, consulta el mejor VPS para Paperclip o la comparativa completa de VPS.