DocWebGestion documentaire auto-hébergée

Guide

Installation

DocWeb tourne sur un NAS Synology ou sur un serveur web ordinaire. Choisissez la voie qui correspond à votre environnement – les étapes pour les outils OCR et la configuration après l'installation valent pour les deux.

Contenu

  1. Prérequis
  2. Voie A : NAS Synology (DSM)
  3. Voie B : serveur web standard
  4. Mettre en place les outils OCR
  5. Après l'installation
  6. Si quelque chose ne fonctionne pas
  7. Connexion

1. Prérequis

DocWeb est volontairement peu exigeant : aucune dépendance à un framework, pas de Node.js, aucune étape de compilation. Il vous faut essentiellement un serveur web avec PHP et une base de données.

Indispensable

  • PHP 8.x (testé avec 8.2) avec les extensions pdo_mysql, mbstring, zip, zlib, json
  • MariaDB 10 (ou MySQL avec les mêmes fonctions), jeu de caractères utf8mb4
  • Apache ou nginx – ou Web Station sur un Synology
  • Droits d'écriture de l'utilisateur du serveur web dans le dossier du projet (pour .env, documents/, inbox/, trash/)

En option – pour la recherche plein texte dans les documents scannés

  • Tesseract (OCR pour les pages scannées et les images)
  • Poppler (pdftotext, pdftoppm)
  • shell_exec doit être autorisé sur le serveur pour que les outils puissent être appelés
Sans ces outils, DocWeb fonctionne quand même. Le texte intégré des PDF est lu même sans Poppler (repli en PHP pur) et les fichiers Office sont analysés via l'extension zip. Seuls les PDF scannés et les images restent alors sans plein texte – le nom de fichier, la catégorie et les étiquettes restent toutefois consultables.
Besoins en espace : DocWeb ne stocke pas les documents en double. Ce qui s'ajoute, ce sont les documents, un cache de texte (index de recherche) et la base de données. Selon le fonds, le cache de texte demande de l'espace supplémentaire.

Voie A

2. NAS Synology (DSM, Web Station)

La voie recommandée si DocWeb doit tourner sur votre propre réseau, sur un Synology. L'accès n'est alors typiquement possible que sur le réseau local ou via un VPN.

  1. Installer Web Station, PHP 8 et MariaDB

    Dans le Centre de paquets du Synology, installer les paquets Web Station, PHP 8.x et MariaDB 10. Ensuite, sous Web Station → Serveur web, créer un serveur web avec PHP 8 s'il n'en existe pas encore.

  2. Placer les fichiers de l'app dans le répertoire web

    Copier le dossier complet du projet vers /volume1/web/docweb – donc le dossier qui contient public/, src/ et sql/. Les dossiers documents/, inbox/ et trash/ sont créés automatiquement lors de l'installation.

  3. Créer la base de données

    Via phpMyAdmin (ou par SSH), créer une base de données avec son utilisateur : 

    CREATE DATABASE docweb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'docweb'@'localhost' IDENTIFIED BY 'DEIN_PASSWORT';
GRANT ALL PRIVILEGES ON docweb.* TO 'docweb'@'localhost';
FLUSH PRIVILEGES;

  4. Créer le fichier de configuration .env

    Dans le dossier du projet (un niveau au-dessus de public/), créer un fichier .env : 

    DB_HOST=localhost
DB_PORT=3307
DB_NAME=docweb
DB_USER=docweb
DB_PASSWORD=DEIN_PASSWORT
    Port : Le paquet MariaDB de Synology écoute par défaut sur le port 3307, pas sur 3306. À adapter en conséquence pour une base de données externe.

  5. Lancer l'installation

    Ouvrir http://NAS-ADRESSE/docweb/install.php dans le navigateur et remplir le formulaire. L'assistant crée toutes les tables, écrit les identifiants dans .env, crée les dossiers et met en place le premier compte administrateur.

    Autrement, par SSH dans le dossier du projet : php install.php. Sans --admin-pass, un mot de passe aléatoire est généré et affiché une seule fois.

    Supprimer ensuite install.php. L'assistant refuse de fonctionner dès qu'un compte utilisateur existe – il n'a néanmoins pas sa place durablement sur le serveur.

  6. Vérifier les réglages PHP

    Sous Web Station → Langages de script → PHP 8.x → Configuration :

    • shell_exec ne doit pas figurer dans disable_functions (sinon pas d'OCR)
    • Activer les extensions : pdo_mysql, mbstring, zip, zlib, json

  7. Installer les outils OCR (en option)

    Pour les documents scannés, mettre en place Tesseract et Poppler – le mode d'emploi se trouve dans la Mettre en place les outils OCR. Sans cette étape, DocWeb fonctionne, mais sans plein texte dans les scans.

  8. Se connecter et lancer la synchronisation

    Se connecter sous http://NAS-ADRESSE/docweb/ et cliquer sur Sync dans la barre supérieure. Exécuter ensuite une fois Reindex si les outils OCR ont été mis en place – les scans déjà présents sont ainsi pris en compte.

Ordre à respecter avec un fonds existant : Placer d'abord les documents dans le dossier de documents, puis lancer la synchronisation. Avec beaucoup de fichiers, la première passe dure d'autant plus longtemps – elle continue en arrière-plan avec affichage de la progression.

Voie B

3. Serveur web standard (Apache ou nginx)

Pour un serveur loué, une machine personnelle ou une machine virtuelle. DocWeb devient alors accessible depuis l'extérieur – accordez donc une attention particulière aux conseils de sécurité à la fin de cette section.

  1. Installer PHP et la base de données

    Sur Debian ou Ubuntu, quelques paquets suffisent : 

    sudo apt install apache2 mariadb-server php php-mysql php-mbstring \
     php-zip php-gd php-curl libapache2-mod-php

sudo mysql_secure_installation

    Pour nginx au lieu d'Apache, installer les mêmes paquets PHP avec php-fpm.

  2. Téléverser le dossier du projet

    Copier le dossier complet du projet sur le serveur. Placez-le en dehors du répertoire accessible publiquement et faites pointer le domaine vers le sous-dossier public/ : 

    /var/www/docweb/            <- dossier du projet (non public)├── public/                 <- le domaine pointe ici├── src/
├── sql/
├── documents/
├── inbox/
└── trash/
    C'est l'installation recommandée. Le code source, la configuration et les documents se trouvent ainsi hors du répertoire web et ne peuvent pas être téléchargés directement.

    Pour Apache, par exemple : 

    <VirtualHost *:443>
    ServerName docweb.example.ch
    DocumentRoot /var/www/docweb/public

    <Directory /var/www/docweb/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

    Le dossier du projet lui-même peut aussi servir de répertoire web – l'application se trouve alors sous /public/ et est accessible par exemple via https://example.ch/public/. Cette disposition est également prise en charge ; la première variante est toutefois plus propre.

  3. Créer la base de données

    sudo mysql -e "CREATE DATABASE docweb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'docweb'@'localhost' IDENTIFIED BY 'DEIN_PASSWORT';"
sudo mysql -e "GRANT ALL PRIVILEGES ON docweb.* TO 'docweb'@'localhost'; FLUSH PRIVILEGES;"

  4. Créer le fichier de configuration .env

    Dans le dossier du projet (un niveau au-dessus de public/) : 

    DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=docweb
DB_USER=docweb
DB_PASSWORD=DEIN_PASSWORT

  5. Définir les droits de fichiers

    L'utilisateur du serveur web (sous Debian/Ubuntu www-data) doit pouvoir écrire dans le dossier du projet – pour .env et les dossiers documents/, inbox/ et trash/ : 

    sudo chown -R www-data:www-data /var/www/docweb
sudo find /var/www/docweb -type d -exec chmod 750 {} \;
sudo find /var/www/docweb -type f -exec chmod 640 {} \;

  6. Lancer l'installation

    Ouvrir https://docweb.example.ch/install.php dans le navigateur et remplir le formulaire. Supprimer ensuite install.php.

    Pas d'accès SSH ? L'assistant travaille entièrement dans le navigateur – vous n'avez besoin d'aucun outil en ligne de commande. L'exploitation courante s'en passe aussi (voir l'étape suivante).

  7. Lancer la première synchronisation

    Après la connexion, cliquer sur Sync dans la barre supérieure. Le déroulement dépend de la possibilité de lancer un PHP en ligne de commande sur le serveur :

    • Avec PHP en ligne de commande : La synchronisation tourne comme processus d'arrière-plan. Si elle est fiable, rien d'autre n'est à faire. Si votre serveur a le binaire PHP à un endroit inhabituel, indiquez le chemin dans .env : PHP_CLI=/usr/bin/php
    • Sans PHP en ligne de commande (typique en hébergement mutualisé, lorsque shell_exec ou popen sont bloqués) : DocWeb bascule automatiquement sur la variante web et traite la synchronisation par petits pas via le serveur web. La barre d'état affiche alors l'indication de laisser la fenêtre ouverte – l'opération continue tant que la page reste ouverte. Si elle est fermée, la prochaine visite reprend au dernier état.
    Adapter la longueur des pas : Si la variante web s'interrompt sur un dépassement de délai, définir une valeur plus petite dans .env, par exemple WEB_WORKER_BUDGET=10 (secondes par pas).

  8. Sécurité en cas d'accès public

    • Utiliser HTTPS – avec Let's Encrypt ou un certificat personnel
    • Faire pointer le domaine vers public/ (voir étape 2) pour que src/, documents/ et .env ne soient pas accessibles par le web
    • Si vous le souhaitez, placer le dossier de documents en dehors du dossier du projet – définir pour cela DOCS_ROOT dans .env, par exemple DOCS_ROOT=/srv/documents
    • Activer la connexion à deux facteurs pour les comptes utilisateurs
    • Mettre en place des sauvegardes régulières (DocWeb crée un ZIP de la base de données et des documents)

Plein texte dans les scans

4. Mettre en place les outils OCR

Ces outils sont facultatifs. Sans eux, la recherche ne trouve aucun texte dans les pages scannées et les images. Avec eux, le contenu est reconnu et devient consultable.

Sur un serveur web standard

Tesseract et Poppler viennent du gestionnaire de paquets, avec les données de langue : 

sudo apt install tesseract-ocr tesseract-ocr-deu tesseract-ocr-eng \
     tesseract-ocr-fra tesseract-ocr-ita poppler-utils

Vérifier ensuite que les outils sont trouvés : 

which pdftotext pdftoppm tesseract
tesseract --list-langs

Sur un NAS Synology

Les anciens paquets pour Tesseract et Poppler ne sont plus disponibles pour les versions récentes de DSM. Deux voies fonctionnent : Entware (binaires directement sur le système de fichiers, recommandé) ou un Docker-Container qui met les binaires à disposition via un répertoire.

Variante 1 : Entware (recommandé)

Se connecter d'abord par SSH en tant que admin et passer à root avec sudo -i. Activer SSH au préalable sous Panneau de configuration → Terminal & SNMP. 

# Créer un répertoire persistant (survit aux mises à jour DSM)
mkdir -p /volume1/@Entware/opt
mount -o bind /volume1/@Entware/opt /opt

# Installer Entware – choisir l'URL correspondant à l'architecture du processeur
# x86_64 (p. ex. RS1221RP) :
wget -O - https://bin.entware.net/x64-k3.2/installer/generic.sh | /bin/sh
# ARMv8 (p. ex. DS920+) :
# wget -O - https://bin.entware.net/aarch64-k3.10/installer/generic.sh | /bin/sh

Installer ensuite les paquets : 

/opt/bin/opkg update
/opt/bin/opkg install tesseract tesseract-data-eng poppler-utils
Important : Le paquet s'appelle poppler-utils, pas poppler. Entware ne propose pas de paquet de langue allemande – deu doit être installé à la main. 
cd /opt/share/tessdata
wget -O deu.traineddata https://raw.githubusercontent.com/tesseract-ocr/tessdata/main/deu.traineddata
/opt/bin/tesseract --list-langs   # « deu » doit apparaître

Les binaires se trouvent ensuite sous /opt/bin/. S'ils ne sont pas trouvés automatiquement, les indiquer dans .env : 

PDFTOTEXT_PATH=/opt/bin/pdftotext
PDFTOPPM_PATH=/opt/bin/pdftoppm
TESSERACT_PATH=/opt/bin/tesseract

Pour que les outils survivent à un redémarrage du NAS, déposer le script fourni dans le Planificateur de tâches (Panneau de configuration → Planificateur de tâches → Tâche déclenchée, déclencheur « Au démarrage », utilisateur root) : 

/bin/sh /volume1/web/docweb/scripts/entware_boot.sh

Le script monte à nouveau /opt, réinstalle Entware et les paquets si nécessaire et s'occupe des données de langue OCR.

Variante 2 : conteneur Docker

Un conteneur met les binaires à disposition via un répertoire partagé : 

docker run -d --name ocr-tools \
  -v /volume1/web/docweb/tools:/tools \
  debian:bookworm-slim \
  bash -c "apt-get update && apt-get install -y tesseract-ocr tesseract-ocr-deu \
           tesseract-ocr-eng poppler-utils && \
           cp /usr/bin/tesseract /usr/bin/pdftotext /usr/bin/pdftoppm /tools/ && sleep infinity"

Comme les fichiers ne sont pas dans le chemin de recherche, définir les chemins dans .env : 

PDFTOTEXT_PATH=/volume1/web/docweb/tools/pdftotext
PDFTOPPM_PATH=/volume1/web/docweb/tools/pdftoppm
TESSERACT_PATH=/volume1/web/docweb/tools/tesseract

Vérifier l'état

Après la connexion, le menu utilisateur en haut à droite indique si les trois outils ont été trouvés : pdftotext (texte des PDF), pdftoppm (rendu des pages) et tesseract (OCR).

Scans déjà existants : Après la mise en place, exécuter une fois Reindex dans la barre supérieure. C'est seulement alors que le plein texte de tous les documents existants est reconstruit.

5. Après l'installation

Premiers pas

  • Connexion : via Connexion ou directement sous https://docweb.gregus.ch/.
  • Changer le mot de passe : changer le mot de passe administrateur choisi lors de l'installation après la première connexion.
  • Créer d'autres utilisateurs : les rôles administrateur, éditeur et lecture déterminent qui peut voir et modifier les documents.
  • Connexion à deux facteurs : recommandé pour les comptes accessibles depuis l'extérieur.
  • Vérifier le dossier de documents : contrôler l'emplacement de stockage sous Paramètres → Base de données – il peut aussi être modifié par la suite, la prochaine synchronisation reprend le nouvel emplacement.
  • Lancer la synchronisation : lit le dossier de documents et ne traite que les fichiers nouveaux, modifiés et supprimés.
  • Lancer la réindexation : une seule fois, après la mise en place de Tesseract et Poppler.

Intégrer des documents au fonds

  • Directement dans le dossier : déposer les fichiers dans le dossier de documents par explorateur de fichiers, SMB ou synchronisation cloud, puis lancer la synchronisation. La structure de dossiers devient les catégories.
  • Via la boîte de réception : les nouveaux scans arrivent d'abord dans la boîte de réception, y sont vérifiés, pivotés et renommés, puis classés dans une catégorie avec des étiquettes – si la catégorie souhaitée manque, elle peut être créée directement lors du classement.
  • Numérisation en lot : toute une pile avec intercalaires est saisie en une seule passe et répartie automatiquement en PDF individuels.
  • Archivage des e-mails : relever les e-mails par IMAP ou POP3 et les classer en PDF.
  • Via l'app iOS : saisir des documents avec l'appareil photo et les classer directement.

Sauvegarde

DocWeb crée une sauvegarde de la base de données et des documents sous forme de ZIP. Comme les documents existent de toute façon comme fichiers ordinaires, une sauvegarde du dossier de documents avec les moyens habituels suffit pour le fonds – pour une migration complète, la base de données et .env en font partie.

6. Si quelque chose ne fonctionne pas

« Le serveur ne répond pas » ou une page blanche

Il manque le plus souvent une extension PHP ou la base de données est injoignable. Consulter la sortie d'erreurs PHP du serveur (Apache : error.log, nginx : /var/log/nginx/error.log). Causes fréquentes : pdo_mysql manquant, mauvais port, mauvais mot de passe dans .env.

L'installation signale que src/config.php est absent

Alors install.php ne se trouve pas dans le dossier du projet, ou le niveau au-dessus ne contient pas de src/. Téléversez le dossier de projet complet – pas seulement le contenu de public/. L'installateur reconnaît lui-même les deux dispositions (dossier du projet et public/).

Une ligne rouge apparaît devant « Dossier » ou « .env »

L'utilisateur du serveur web n'a pas le droit d'écrire dans le dossier du projet. Définir les droits selon l'étape 5 (voie B). Sur un Synology, vérifier que le dossier partagé est accessible en écriture pour l'utilisateur de Web Station.

Après la synchronisation, le plein texte manque dans les scans

Les outils OCR manquent ou ne peuvent pas être appelés. Le menu utilisateur montre l'état des trois outils. Si les trois manquent, shell_exec est généralement bloqué dans disable_functions – ou les chemins doivent être définis dans .env. Après correction, exécuter une fois Reindex.

Les fichiers Word, Excel et PowerPoint ne peuvent pas être recherchés

Cela nécessite l'extension PHP zip. L'activer et relancer la réindexation.

« La synchronisation n'a pas pu être démarrée » ou l'opération reste bloquée

Sur les serveurs sans PHP en ligne de commande démarrable, la variante web prend automatiquement le relais (voir étape 7 de la voie B). Si le message apparaît malgré tout, vérifier :

  • JavaScript est-il activé dans la fenêtre du navigateur ? Le pilotage passe par le navigateur.
  • Si l'exécution s'interrompt au bout d'un moment, définir une valeur plus petite pour WEB_WORKER_BUDGET dans .env (p. ex. 10).
  • Y a-t-il un chemin en ligne de commande qui pourrait aider dans .env ? PHP_CLI=/usr/bin/php

L'exécution s'arrête quand j'ouvre d'autres pages

En mode web, c'est le navigateur qui exécute les étapes de travail. Si la page est fermée, l'opération est suspendue – rien n'est perdu. La prochaine visite reprend au dernier état.

J'ai oublié le mot de passe administrateur

L'installateur ne crée pas de second compte dès qu'un compte existe – c'est voulu. Réinitialisez le mot de passe directement dans la base de données ou créez un nouvel utilisateur avec le rôle administrateur via phpMyAdmin.