Comment auto-héberger Paperclip sur un VPS (Guide étape par étape 2026)

Comment auto-héberger Paperclip sur un VPS (Guide étape par étape 2026)

Paperclip est l’un des systèmes de gestion documentaire auto-hébergés les plus propres disponibles. Il tourne comme un conteneur Docker unique, stocke les fichiers sur un volume local et expose une interface web sur le port 8080. Ce guide vous accompagne dans une installation complète et prête pour la production sur un VPS Linux — de la commande du serveur au premier document importé.

Prérequis

• Un VPS sous Ubuntu 22.04 LTS ou Debian 12 (recommandé)
• Au minimum 1 vCPU, 1 Go de RAM, 20 Go de stockage (2 Go de RAM recommandés pour l’OCR)
• Accès root ou sudo via SSH
• Un nom de domaine ou sous-domaine pointant vers l’IP du VPS (optionnel mais recommandé pour HTTPS)

Options VPS recommandées :

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

Étape 1 : Mettre à jour le serveur

apt update && apt upgrade -y

Étape 2 : Installer Docker

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

Vérifier l’installation de Docker :

docker --version

Étape 3 : Installer Docker Compose

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

Étape 4 : Créer un répertoire de travail

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

Étape 5 : Créer un fichier docker-compose.yml

nano /opt/paperclip/docker-compose.yml

Coller la configuration suivante :

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=remplacer_par_une_cle_aleatoire
      - PAPERCLIP_OCR_ENABLED=true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  paperclip_data:

Important : remplacez remplacer_par_une_cle_aleatoire par une chaîne aléatoire. Générez-en une avec :

openssl rand -hex 32

Étape 6 : (Optionnel) Utiliser PostgreSQL à la place de SQLite

Pour un usage multi-utilisateurs ou en production, étendez le fichier 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: mot_de_passe_fort
    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=votre_cle_aleatoire
      - PAPERCLIP_DB_HOST=db
      - PAPERCLIP_DB_NAME=paperclip
      - PAPERCLIP_DB_USER=paperclip
      - PAPERCLIP_DB_PASSWORD=mot_de_passe_fort
      - PAPERCLIP_OCR_ENABLED=true

volumes:
  paperclip_data:
  pg_data:

Étape 7 : Démarrer Paperclip

cd /opt/paperclip
docker compose up -d

Vérifier que le conteneur a démarré :

docker compose ps
docker compose logs -f paperclip

Étape 8 : Configurer le pare-feu

ufw allow OpenSSH
ufw allow 80
ufw allow 443
ufw enable

Note : le port 8080 n’est pas exposé directement — le trafic passe par Caddy/Nginx avec HTTPS.

Étape 9 : Configurer HTTPS avec Caddy

apt install caddy -y

Modifier le Caddyfile :

nano /etc/caddy/Caddyfile

docs.votredomaine.fr {
    reverse_proxy localhost:8080
}

Recharger Caddy :

systemctl reload caddy

Caddy provisionne automatiquement un certificat Let’s Encrypt.

Étape 10 : Première connexion

1. Ouvrez https://docs.votredomaine.fr (ou http://VOTRE_IP_VPS:8080 sans domaine)
2. Complétez l’assistant de configuration initial — définissez votre email et mot de passe admin
3. Importez votre premier document
4. Activez l’OCR si vous avez besoin de la recherche plein texte sur les fichiers numérisés

Étape 11 : Configurer les sauvegardes

Sauvegardez le volume Docker en local ou dans un bucket compatible S3 :

# Sauvegarde vers un fichier local
docker run --rm \
  -v paperclip_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/paperclip-backup-$(date +%Y%m%d).tar.gz /data

Planifier via cron :

crontab -e
# Ajouter :
0 3 * * * /opt/paperclip/backup.sh

Résolution de problèmes

Pour les recommandations de fournisseurs VPS, consultez le meilleur VPS pour Paperclip ou le comparatif VPS complet.