Service de documents

Le service de documents génère des PDF à partir de documents Word (LibreOffice), anonymise des PDF (PDFium), lit les scans et les photos (OCR Tesseract), et fusionne et découpe des PDF. C’est une image à part, ghcr.io/kuznyaoff/loopandroll-documents, partagée par toutes les instances d’un hôte : les instances l’appellent en HTTP, il ne garde rien.

Sans lui, Loop & Roll fonctionne comme avant : les nœuds de documents ne sont pas proposés, et les pièces jointes scannées sont signalées comme non lues.

Le lancer

Ajoutez le service à côté de vos instances, sur un réseau privé qu’elles partagent, et donnez à chaque instance son adresse et un jeton :

services:
  documents:
    image: ghcr.io/kuznyaoff/loopandroll-documents:main
    restart: unless-stopped
    environment:
      DOCUMENTS_TOKENS: ${DOCUMENTS_TOKEN}
    mem_limit: 2g
    read_only: true
    tmpfs:
      - /tmp:size=1g
    networks: [documents]

  app:
    environment:
      DOCUMENTS_URL: http://documents:8080
      DOCUMENTS_TOKEN: ${DOCUMENTS_TOKEN}
    networks: [default, documents]

networks:
  documents:
    internal: true

internal: true est la ligne importante : le service n’a aucun accès sortant. LibreOffice ne télécharge jamais une image liée par URL dans un modèle, et rien de ce que contient un document ne peut faire appeler quoi que ce soit au service.

Générez un jeton avec openssl rand -hex 32 (32 caractères au moins).

Les variables du service

Variable	Défaut	Rôle
DOCUMENTS_TOKENS	— (obligatoire)	Les jetons acceptés, séparés par des virgules (32 caractères au moins chacun). Un par instance, ou un par hôte ; plusieurs permettent une rotation sans coupure.
PORT	8080	Port d’écoute.
MAX_CONCURRENCY	2	Travaux simultanés. Au-delà, une requête attend QUEUE_WAIT_SECONDS, puis reçoit 503 busy (l’instance retente).
QUEUE_WAIT_SECONDS	20	Attente d’une place libre.
JOB_TIMEOUT_SECONDS	120	Budget de temps d’un travail ; au-delà, le travail et ses processus sont tués (504 timeout).
JOB_MEMORY_MB	1536	Espace d’adressage d’un travail PDF (PDFium, Tesseract). Un document qui en demande plus échoue en too_complex.
MAX_DOCUMENT_MB	25	Taille d’un document.
MAX_REQUEST_MB	70	Taille d’un corps de requête (base64 compris).
MAX_PAGES	100	Pages d’un PDF à anonymiser ou à lire.
MAX_PAGES_STRUCTURAL	1000	Pages d’un PDF à fusionner ou découper.
MAX_MERGE_DOCUMENTS	20	PDF d’une même fusion.
RENDER_DPI	200	Résolution des pages caviardées.
OCR_LANGUAGES	fra+eng	Langues de Tesseract (l’image embarque le français et l’anglais).
LOG_LEVEL	info	debug, info, warning, error.

Comptez MAX_CONCURRENCY × JOB_MEMORY_MB plus environ 300 Mo, et réglez la limite mémoire du conteneur en conséquence.

Les variables de l’instance

Variable	Défaut	Rôle
DOCUMENTS_URL	—	L’adresse du service, par exemple http://documents:8080.
DOCUMENTS_TOKEN	—	Un des jetons du service (DOCUMENTS_TOKEN_FILE fonctionne aussi). L’URL et le jeton, ou aucun : l’un sans l’autre est signalé au démarrage et le service reste éteint.
DOCUMENTS_TIMEOUT_SECONDS	150	Budget de temps d’un appel, côté instance. Gardez-le au-dessus du JOB_TIMEOUT_SECONDS du service.
DOCUMENTS_MAX_MB	25	Taille d’un document envoyé au service.

Ce qu’il garde, ce qu’il journalise

Rien n’est stocké : chaque travail tourne dans son propre processus, dans un dossier temporaire supprimé à la fin, avec son propre profil LibreOffice. Les journaux portent une ligne par requête — route, statut, code d’erreur, instance appelante, tailles en octets, durée — et jamais un document, un terme recherché ou un nom de fichier.

Surveiller

• GET /healthz répond 200 {"status":"ok"} sans jeton ; l’image a une sonde de santé Docker.
• Côté instance, un service injoignable ou occupé fait échouer les étapes de documents de façon transitoire : elles sont retentées (trois tentatives). Les documents invalides (PDF protégé par mot de passe, modèle mal formé) échouent définitivement, avec une raison.
• Un 401 du service veut dire que le jeton de l’instance n’est pas dans DOCUMENTS_TOKENS : les étapes échouent en document.not_configured.

Dépanner

Symptôme	Cause
Les nœuds n’apparaissent pas dans la palette	DOCUMENTS_URL ou DOCUMENTS_TOKEN manque sur l’instance (voir les avertissements de démarrage).
document.service_unavailable à chaque exécution	L’instance ne joint pas le service : réseau, nom, port, ou service arrêté.
Beaucoup de 503 busy	Montez MAX_CONCURRENCY (et la limite mémoire), ou ajoutez une réplique.
too_complex sur un gros scan	Montez JOB_MEMORY_MB, ou baissez RENDER_DPI.
Les PDF générés ne se mettent pas en page comme dans Word	Une police du modèle manque : l’image embarque DejaVu, Liberation, Carlito et Caladea (équivalents métriques de Calibri et Cambria).