infra/stacks/paperless.opytex.org/README.md

Paperless-ngx — paperless.opytex.org

Gestion documentaire (OCR + indexation). Cinq conteneurs : webserver (l'application), db (PostgreSQL), broker (Valkey, file de tâches), gotenberg et tika (conversion des documents bureautiques et des .eml).

Authentification : SSO Authentik, plus un compte admin local (waha-local) qui sert de porte de secours si le SSO tombe.

Déploiement

Depuis ce dossier, sur chioggia :

sops exec-env secrets.env.yaml 'docker compose up -d'

Le nom du dossier (paperless.opytex.org) donne le nom de projet Compose paperlessopytexorg, dont dérivent le volume paperlessopytexorg_valkeydata et le nom du dump de base. Renommer ce dossier ferait repartir la stack sur des volumes vides.

Après une rotation de secret, docker compose up -d répond « up to date » et garde l'ancienne valeur :

sops exec-env secrets.env.yaml 'docker compose up -d --force-recreate'

Les secrets sont déclarés ${VAR:?} dans le compose : toute commande docker compose échoue sans l'enveloppe sops exec-env, y compris stop, exec, logs et ps. Pour enchaîner plusieurs commandes, une seule enveloppe suffit :

sops exec-env secrets.env.yaml '
  docker compose stop webserver &&
  docker compose exec -T db psql -U paperless -d paperless -c "..." &&
  docker compose up -d
'

Secrets

Quatre valeurs dans secrets.env.yaml, injectées par sops exec-env : PAPERLESS_SECRET_KEY, PAPERLESS_DBPASS, PAPERLESS_ADMIN_PASSWORD et SSO_CLIENT_SECRET. La clé age de waha permet de les éditer directement sur chioggia, sans jamais écrire de fichier en clair :

sops edit secrets.env.yaml

PAPERLESS_DBPASS ne se change pas seul : PostgreSQL ignore POSTGRES_PASSWORD sur un PGDATA déjà initialisé, une nouvelle valeur ne ferait donc que casser la connexion de l'application, en boucle de redémarrage. Il faut la changer aussi dans la base (ALTER USER).

Le client_id SSO n'est pas un secret : il est en clair dans docker-compose.yml, avec le reste du bloc PAPERLESS_SOCIALACCOUNT_PROVIDERS.

Le même identifiant sous deux noms

La base est nommée par deux jeux de variables, dans env_file :

• PAPERLESS_DBNAME / PAPERLESS_DBUSER : lus par webserver pour se connecter.
• POSTGRES_DB / POSTGRES_USER : lus par db, et par le script de sauvegarde qui fait docker exec printenv POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD sur le conteneur db. Le script retombe silencieusement sur postgres si la variable manque : le dump réussirait alors sur la mauvaise base.

Les deux jeux doivent porter la même valeur. POSTGRES_PASSWORD fait exception : il n'est pas dans env_file, il vient de SOPS via PAPERLESS_DBPASS, dans le bloc environment: du service db.

consume et export

Volume	Rôle
consume	tout fichier déposé ici est ingéré puis supprimé
export	destination de document_exporter

Ce sont des volumes Docker et non des dossiers de ce dépôt : les données restent hors de l'arbre versionné, et un déplacement du dépôt ne les emmène pas. Ils naissent avec l'UID/GID du chemin correspondant dans l'image (1000), donc sans chown à faire.

Déposer un fichier à ingérer passe par l'UI, ou :

docker cp fichier.pdf paperlessopytexorg-webserver-1:/usr/src/paperless/consume/

Générer une archive lisible sans Paperless :

sops exec-env secrets.env.yaml \
  'docker compose exec webserver document_exporter ../export'

Volumes

Volume	Contenu	Sauvegarde
paperless-data	index de recherche, classifieur, base des tâches	label backup.enable=true + MANUAL_VOLUMES
paperless-media	les documents originaux et leurs archives PDF	label backup.enable=true + MANUAL_VOLUMES
paperless-pg-data	base PostgreSQL	dump SQL (backup.type=postgres sur le conteneur db)
paperlessopytexorg_valkeydata	file de tâches Celery (Valkey)	non sauvegardé, volontairement — reconstruit
paperlessopytexorg_export	archive document_exporter, lisible sans Paperless	label backup.enable=true sur le volume
paperlessopytexorg_consume	sas d'ingestion	non sauvegardé, volontairement — transitoire

Les trois premiers portent un name: explicite, sans préfixe de projet.

Les labels de volume ne s'appliquent qu'à la création : en ajouter un — ou en retirer un — ne changerait rien au volume réel, mais ferait diverger sa déclaration, et Compose proposerait alors de le recréer. Répondre « y » à cette question détruirait les documents.

paperless-data et paperless-media figurent en plus dans MANUAL_VOLUMES (backup.conf), ce qui les fait sauvegarder deux fois — sans conséquence, restic déduplique. paperless-pg-data n'a délibérément aucun label : sauvegarder les fichiers d'un PostgreSQL en cours d'écriture ne donne pas une base restaurable, c'est le dump SQL qui le couvre.

Version des images

Paperless-ngx applique des migrations de schéma irréversibles à chaque montée de version : une mise à jour se fait seule, après sauvegarde vérifiée, et ne se revient pas en repassant l'image à la version précédente.

Toutes les images sont épinglées au patch, y compris apache/tika que la documentation amont laisse en latest : un tag flottant rend la stack non reproductible et fait franchir des versions au prochain pull, sans que rien ne l'annonce.

Références :

• https://docs.paperless-ngx.com/configuration/
• https://docs.goauthentik.io/integrations/services/paperless-ngx/