Aller au contenu principal

Paperless-ngx sur Google Cloud Run

Paperless-ngx sur Google Cloud Run

Ce document fournit une référence complète pour le module modules/Paperless_CloudRun. Il couvre l'architecture, IAM, les variables de configuration, les comportements spécifiques à Paperless-ngx et les modèles opérationnels pour le déploiement de Paperless-ngx sur Google Cloud Run (v2).


Ce que coûte Paperless sur RAD, et comment cela se compare​

Pour une archive de bureau, Paperless sur le module Cloud Run de RAD coûte environ 99 $ US par mois, sans licence par utilisateur. Un serveur autogéré est moins cher en espèces, mais vous gérez alors vous-même la base de données, les sauvegardes, les correctifs de sécurité et les mises à niveau. Les chiffres sont au 8 octobre 2026 ; les sources sont listées à la fin de cette section.

Si vous n'en avez besoin qu'occasionnellement — pour préparer une certification, une démo, une activité saisonnière — un projet géré par RAD peut être supprimé et restauré dans les 30 jours sans frais supplémentaires, de sorte que ces 99 $ US deviennent quelques dollars par mois. Voir Mettez-le en pause gratuitement, ci-dessous.

Ce que vous payez sur RAD​

Dans un projet Google Cloud que vous possédezDans un projet que RAD gère pour vous
Frais de module, une fois par déploiement110 crédits (11 $ US au prix de la recharge)99 crédits (10 % de moins)
BuildsInclus dans le prix : pas de frais de build pour la création, 5 mises à jour par mois (mois calendaire UTC) gratuites puis 2 crédits chacune, et rien pour la suppression ou pour un build échoué, dans la limite de 10 builds échoués par jour (UTC). Les sessions de lab et les projets clients sont l'exception : ils sont toujours facturés à la minute pour le temps de buildIdem
Coût d'exécution Google CloudFacturé par Google à votre propre compte de facturation (tableau ci-dessous)Mesuré à l'heure en crédits ; RAD publie 67 crédits par jour, soit environ 2 010 par mois (environ 201 $ US au prix de la recharge)
Qui possède quoiVous possédez le projet et sa facturation ; RAD le déploie et le met à jourRAD possède le projet, avec des garde-fous, des quotas et des alertes budgétaires ; vous avez accès à la console, et un solde minimum acheté est conservé en réserve

Votre premier déploiement réussi sur RAD est exempt de frais de module, quel que soit le montant des frais : une fois par compte, pour un module que vous déployez et payez vous-même (dans une solution, les frais d'une application : la première à réussir ; jamais une session de lab ou un projet client).

10 crédits coûtent 1 $ US pour une recharge ponctuelle, et moins pour un plan mensuel. Dans un projet géré par RAD, la base de données, le serveur de fichiers et le réseau sont partagés par toutes les applications du projet, de sorte qu'une deuxième application n'ajoute pas une deuxième base de données.

Coût d'exécution par défaut dans votre propre projet (us-central1, prix catalogue Google) :

Ressource (valeur par défaut du module)Par mois
Cloud Run, 2x vCPU / 2 Gio (scaleToZero)28,37 $ US
Cloud SQL pour PostgreSQL, 1 vCPU / 3,75 Go, zonal, 10 Go SSD51,02 $ US
Serveur de fichiers NFS/cache (petite VM)13,43 $ US
Cloud NAT et réseau5 $ US
Cloud Storage (modules complémentaires, sauvegardes)1 $ US
Totalenviron 99 $ US
  • Cloud SQL et Cloud Run coûtent le même prix en africa-south1 (Johannesburg) ; la VM coûte environ 10 % de plus.
  • La mise à l'échelle à zéro est la valeur par défaut. La ligne Cloud Run ci-dessus reflète déjà ce coût ; le réglage min_instance_count = 1 maintient une instance chaude et augmente cette ligne, en échange de l'absence de démarrages à froid.
  • Évitez Filestore pour un petit déploiement. Le module utilise une petite VM NFS/cache par défaut. La plus petite instance de Filestore est de 1 Tio, ce qui coûte environ 164 $ US par mois à elle seule.

Comment cela se compare​

  • Aucun fournisseur ne vend un "Paperless-ngx Cloud" officiel hébergé avec des prix publics, donc cette comparaison se fait avec un serveur nu.
  • Un VPS nu dimensionné près de l'empreinte de Paperless-ngx — Hetzner CPX22 ou un Droplet DigitalOcean 2 vCPU/4 Go, tous deux à environ 24 $/mois, ou un GCP Compute Engine e2-standard-2 (2 vCPU/8 Go) à environ 49 $/mois — est moins cher en espèces que les chiffres RAD ci-dessus.
  • La différence est ce que RAD gère : le stockage de documents adossé à GCS, les sauvegardes Cloud SQL et la récupération à un instant précis, Redis pour la file d'attente OCR/consommation, et Secret Manager pour le mot de passe administrateur — tout est inclus plutôt qu'auto-administré.
  • Si Paperless doit rester actif sans mise à l'échelle à zéro, ou fonctionner à côté d'autres charges de travail Kubernetes, consultez plutôt le guide GKE — environ 143 $ US par mois dans votre propre projet, ou 3 390 crédits (environ 271-339 $ US) par mois dans un projet géré par RAD.

Mettez-le en pause gratuitement : supprimez un projet géré par RAD, restaurez-le quand vous en avez besoin​

Si Paperless s'exécute dans un projet que RAD gère pour vous, vous avez une deuxième option qui va bien au-delà de la mise à l'échelle à zéro : supprimez l'ensemble du projet et restaurez-le dans les 30 jours pour presque rien. Cela convient bien mieux à une utilisation occasionnelle — préparation d'une certification, environnement de démonstration, activité saisonnière — que l'exécution continue de Paperless.

Une restauration n'est pas garantie — conservez vos propres sauvegardes. Les conditions de Google Cloud ne garantissent pas qu'un projet restauré, ou les ressources qu'il contient, sera utilisable après sa restauration, de sorte que la restauration ne peut pas être considérée comme un moyen de récupérer un projet supprimé. Avant de supprimer, assurez-vous d'avoir effectué des sauvegardes appropriées des données et de la configuration de l'application et de les avoir stockées en dehors du projet. Si une restauration échoue, ou si le projet restauré ne fonctionne pas, la solution de repli consiste à redéployer l'application (voir la section suivante) et à restaurer sa configuration et ses données à partir de ces sauvegardes.

  • Comment ça marche. La suppression d'un projet géré par RAD délie d'abord sa facturation, puis demande à Google de supprimer le projet. Google ne supprime pas le projet immédiatement : il le conserve, récupérable, pendant 30 jours. Comme la facturation est déjà déliée, rien n'est facturé pendant cette attente. Contrairement à la suppression d'un module, cela ne supprime pas Cloud SQL, aucune VM ou Cloud Run un par un — l'ensemble du projet, et tout ce qu'il contient, s'arrête simplement.
  • La restauration est une vérification, pas une reconstruction. Dans les 30 jours, le propriétaire du projet peut le restaurer. RAD demande à Google de récupérer le projet et de rattacher son compte de facturation, puis vous demande d'exécuter Update sur chaque déploiement pour confirmer que tout est revenu. Comme rien n'a été détruit individuellement, cette mise à jour trouve les mêmes ressources déjà présentes — c'est une vérification, pas une reconstruction, et une mise à jour ne facture jamais les frais de module à nouveau. Les mises à jour sont incluses dans le prix (5 par mois pour chaque déploiement), donc une restauration ne coûte normalement aucun crédit.
  • Ainsi, un mois d'utilisation occasionnelle peut coûter quelques dollars, et non les 201 $ US par mois pour le maintenir en fonctionnement. Déployez Paperless, utilisez-le pendant un certain temps, supprimez le projet. Restaurez-le la prochaine fois que vous en avez besoin, confirmez avec Update, et supprimez-le à nouveau lorsque vous avez terminé. Vous ne payez les frais de module qu'une seule fois et le temps pendant lequel Paperless a été réellement actif.
  • Ce que cela nécessite. Vous devez être propriétaire du projet (pas un projet que vous apportez et dont RAD ne gère que la facturation), et vous le restaurez vous-même dans les 30 jours — après cela, Google le supprime définitivement. La restauration est admise comme la création d'un nouveau projet : votre solde de crédits achetés doit toujours dépasser le seuil du palier (100 crédits pour le palier sandbox qui convient à la plupart des utilisations d'étude et de démonstration). Google indique que la plupart des services sont de nouveau pleinement fonctionnels dans les 36 heures suivant une restauration.
  • Une lacune réelle : le bucket de sauvegarde ne survit pas. Les sauvegardes de Paperless sont écrites dans un bucket à l'intérieur du projet, et ce bucket n'est pas protégé par la suppression logicielle de Cloud Storage, il est donc très probable qu'il disparaisse dès que vous supprimez le projet — même si le projet lui-même est récupérable pendant 30 jours. Si vous avez apporté des modifications à Paperless que vous souhaitez conserver, copiez une sauvegarde (vers Google Drive, ou un bucket en dehors du projet) avant de supprimer, comme pour le flux de travail de redéploiement ci-dessous. Pour une installation par défaut sans rien d'irremplaçable, cela n'a pas d'importance.

Payez uniquement pendant que vous l'utilisez, l'autre méthode : supprimer et redéployer​

Cloud Run se met déjà à l'échelle à zéro entre les requêtes. L'option ci-dessus ne s'applique qu'à un projet géré par RAD ; dans votre propre projet, ou une fois la fenêtre de 30 jours passée, la façon d'arrêter de payer est de supprimer le déploiement et de le déployer à nouveau lorsque vous en avez besoin.

  • Ce que coûte un redéploiement. Les frais de module à nouveau (les builds sont inclus) : 110 crédits (11,00 $ US), car RAD recrée le projet et les services partagés avant Paperless. La suppression ne permet d'économiser de l'argent que si Paperless resterait inutilisé pendant environ 4 jours ou plus, à la fois dans votre propre projet (environ 3,29 $ US par jour) et dans un projet géré par RAD (67 crédits par jour).
  • La majeure partie du coût d'exécution est généralement la base de données et la VM de fichier/cache partagée. Elles ne s'arrêtent que si rien d'autre dans le projet ne les utilise, donc la suppression de Paperless alors que quelque chose d'autre partage le projet n'économise que la partie calcul de Paperless.
  • Conservez d'abord les données. Les sauvegardes sont écrites dans un bucket à l'intérieur du déploiement et sont supprimées avec lui, donc copiez la dernière sauvegarde avant de la supprimer si vous voulez la conserver.
  • RAD ne recrée pas un déploiement supprimé pour vous ; vous entrez à nouveau les paramètres lors du déploiement.

Sessions de lab et environnements gérés​

  • Sessions de lab, pour la formation. Un formateur anime une session pour une classe. Chaque participant reçoit l'application dans son propre projet Google Cloud pendant 15 minutes à 24 heures, dans la limite d'une allocation définie par le formateur. Le formateur peut aussi créer un seul environnement partagé pour toute la classe, et chacun utilise alors la même application et ses données. Soit le formateur finance toutes les places, soit chaque participant paie la sienne. Tout est supprimé à la fin de la session et les crédits inutilisés sont reversés au formateur.
  • Environnements gérés, pour les sociétés de conseil. Un partenaire exécute l'application pour un client à partir d'un portefeuille cloisonné qu'il finance, et règle directement avec le client. Si le portefeuille est faible, la facturation est suspendue et les données sont conservées, de sorte que personne ne reçoit de frais inattendus. À la fin, le partenaire transfère le projet et les déploiements deviennent la propriété du client.

Les crédits peuvent être achetés dans plus de 20 devises, y compris XAF, XOF, NGN, GHS, KES et ZAR, par carte, virement bancaire ou argent mobile.

Sources (8 octobre 2026) : Prix catalogue Google Cloud de l'API Cloud Billing Catalog ; radmodules.dev/pricing pour les frais propres à RAD et les estimations de crédits quotidiens ; Supprimer et restaurer des projets pour la fenêtre de pause/restauration et ce qu'elle dit sur les objets Cloud Storage sans suppression logicielle.


1. Vue d'ensemble du module​

Paperless-ngx est un système de gestion de documents open source soutenu par la communauté qui transforme les documents papier en une archive numérique consultable. Paperless CloudRun est un module wrapper construit sur App CloudRun. Il utilise App CloudRun pour toute la provision d'infrastructure GCP et injecte la configuration d'application spécifique à Paperless-ngx, l'initialisation de la base de données et la configuration de stockage via Paperless Common.

Capacités clés :

  • Calcul : Cloud Run v2 (Gen2), conteneur Python/gunicorn, 2 vCPU / 2 Gio par défaut. min_instance_count = 0 par défaut (mise à l'échelle à zéro) — défini sur 1 ou plus pour maintenir le pipeline de consommation en arrière-plan chaud et éviter les retards de démarrage à froid lors du téléchargement de documents.
  • OCR et classification : Moteur OCR Tesseract avec packs de langues configurables (ocr_language). Classification de documents par apprentissage automatique, recherche en texte intégral, étiquettes, correspondants, types de documents et champs personnalisés.
  • Persistance des données : Cloud SQL PostgreSQL 15. Volume GCS FUSE monté automatiquement à /usr/src/paperless/media pour le stockage persistant des documents (documents traités, miniatures, originaux).
  • File d'attente des tâches : Redis obligatoire (non optionnel). Paperless-ngx utilise Redis comme courtier de messages Celery pour le traitement OCR en arrière-plan, la classification des documents, le pipeline de consommation et les tâches asynchrones.
  • Sécurité : Hérite de Cloud Armor WAF, IAP, Binary Authorization et VPC Service Controls de App CloudRun. Deux secrets générés automatiquement par Paperless Common : PAPERLESS_ADMIN_PASSWORD et PAPERLESS_SECRET_KEY.
  • CI/CD : Pipeline d'images personnalisées Cloud Build par défaut ; livraison progressive Cloud Deploy en option.
  • Fiabilité : Les sondes de santé ciblent / (la page de connexion Paperless-ngx) avec un délai initial de 60 secondes pour tenir compte des migrations de base de données et du démarrage du worker Celery au premier démarrage.

Identité du projet et de l'application

VariableGroupeTypeValeur par défautDescription
project_id1string—ID du projet GCP. Obligatoire.
tenant_id2string'demo'Suffixe court ajouté à tous les noms de ressources.
support_users2list(string)[]Destinataires des e-mails pour les alertes de surveillance.
resource_labels2map(string){}Étiquettes appliquées à toutes les ressources provisionnées.
application_name3string'paperless'Nom de ressource de base. Ne pas modifier après le déploiement initial.
display_name3string'Paperless-ngx - Document Management System'Nom lisible par l'homme affiché dans les tableaux de bord.
description3string'Paperless-ngx - open-source document management system with OCR...'Description du service.
application_version3string'latest'Tag de version de l'image du conteneur. Épinglez à une version spécifique (par exemple, '2.13.5') pour la production.

Architecture du wrapper : Paperless CloudRun appelle Paperless Common pour construire un objet application_config contenant des variables d'environnement spécifiques à Paperless-ngx, la configuration de la sonde, les définitions de bucket de stockage et la définition de job db-init. module_storage_buckets contient le bucket paperless-media provisionné par Paperless Common. scripts_dir est résolu vers le répertoire de scripts Paperless Common au moment de l'apply.


2. IAM et contrôle d'accès​

Paperless_CloudRun délègue tout le provisionnement IAM à App_CloudRun. Les ensembles de rôles Cloud Run SA, Cloud Build SA, agent de service IAP et rotation de mot de passe sont identiques à ceux de App_CloudRun.

Secrets d'application : Contrairement à Ghost, Paperless Common génère automatiquement deux secrets au niveau de l'application au moment du déploiement :

SecretDescription
PAPERLESS_ADMIN_PASSWORDMot de passe du compte administrateur initial. Généré automatiquement et stocké dans Secret Manager.
PAPERLESS_SECRET_KEYClé secrète de l'application Django. Générée automatiquement et stockée dans Secret Manager.

Les deux secrets sont injectés nativement par Cloud Run au démarrage de la révision — le texte en clair n'est jamais écrit dans l'état Terraform.

Identité d'initialisation de la base de données : Le job Cloud Run db-init s'exécute sous le SA Cloud Run. Il se connecte à Cloud SQL PostgreSQL via le socket Unix du proxy d'authentification (depuis enable_cloudsql_volume = true par défaut).

Délai de propagation IAM de 120 secondes : Hérité de App CloudRun — le service Paperless-ngx n'est pas déployé tant que le délai n'est pas écoulé, ce qui empêche les échecs de lecture de secrets au premier démarrage de la révision.

Pour les tableaux de rôles complets et les détails IAP, de rotation de mot de passe et d'accès public, consultez la documentation App_CloudRun.


3. Configuration du service principal​

A. Calcul (Cloud Run)​

Paperless-ngx est une application Python Django/gunicorn avec des workers Celery en arrière-plan. Elle effectue l'OCR à l'aide de Tesseract, qui est gourmand en CPU lors de l'ingestion de documents. Paperless CloudRun expose cpu_limit et memory_limit comme des variables de haut niveau dédiées avec des valeurs par défaut prêtes pour la production.

min_instance_count = 0 et cpu_always_allocated = false par défaut. Comme la plupart des modules de ce dépôt, Paperless-ngx se met à l'échelle à zéro et facture sur la base des requêtes par défaut (coût d'abord). L'inconvénient : le consommateur de documents en arrière-plan + le worker OCR ne s'exécutent que lorsqu'une instance est chaude, de sorte que les documents déposés dans le répertoire de consommation peuvent rester non traités jusqu'à ce que la prochaine requête réveille le service. Le réglage de min_instance_count = 1 seul ne suffit pas à restaurer le traitement continu — la facturation basée sur les requêtes (cpu_always_allocated = false) continue de limiter le CPU à près de zéro entre les requêtes. Définissez à la fois cpu_always_allocated = true et min_instance_count = 1 ou plus pour maintenir le pipeline de consommation en écoute continue avec un CPU alloué.

Le Startup CPU Boost est toujours activé (codé en dur dans App CloudRun).

Image du conteneur : container_image_source par défaut 'custom', ce qui signifie que Cloud Build compile une image personnalisée à l'aide du Dockerfile de Paperless_Common (basé sur ghcr.io/paperless-ngx/paperless-ngx). Définissez container_image_source = 'prebuilt' et container_image = 'ghcr.io/paperless-ngx/paperless-ngx:2.13.5' pour déployer directement une image existante.

Mise en miroir d'images activée par défaut (enable_image_mirroring = true) : Les images Paperless-ngx sont hébergées sur GitHub Container Registry (GHCR). Le module met en miroir l'image vers Artifact Registry pour éviter les limites de débit de GHCR et pour satisfaire les exigences de Binary Authorization.

VariableGroupeValeur par défautDescription
deploy_application4trueDéfinissez false pour un déploiement d'infrastructure uniquement (SQL, stockage, secrets).
container_image_source—'custom''custom' construit via Cloud Build. 'prebuilt' déploie un URI d'image existant.
container_image—""Remplace l'URI de l'image. Laissez vide pour que Cloud Build le gère.
cpu_limit4'2000m'CPU par instance. 2 vCPU recommandés pour les charges de travail OCR.
memory_limit4'2Gi'Mémoire par instance. 2 Gio minimum ; augmentez pour les grands lots de documents.
cpu_always_allocated4falsefalse = démarrage à froid axé sur les coûts (facturation basée sur les requêtes) ; le consommateur de documents + le worker OCR arrêtent le traitement lorsqu'ils sont mis à l'échelle à zéro. Définissez true et min_instance_count >= 1 ensemble pour restaurer le fonctionnement continu.
min_instance_count40Instances minimales en cours d'exécution. Mise à l'échelle à zéro par défaut ; définissez sur 1+ et cpu_always_allocated = true pour maintenir le pipeline de consommation actif.
max_instance_count43Instances maximales en cours d'exécution. Plafond de coût.
container_port48000Port gunicorn de Paperless-ngx. Ne pas modifier sans faire correspondre le Dockerfile.
execution_environment4'gen2'Gen2 requis pour les montages de volume GCS Fuse.
timeout_seconds4300Durée maximale de la requête. L'OCR sur de grands documents peut être lent ; 300s ou plus recommandé.
enable_cloudsql_volume4truePar défaut true — se connecte via le socket Unix du proxy d'authentification Cloud SQL.
enable_image_mirroring4trueMet en miroir l'image GHCR dans Artifact Registry. Recommandé pour éviter les limites de débit.
container_protocol4'http1''http1' ou 'h2c'.
traffic_split4[]Allocation de trafic canary/bleu-vert basée sur un pourcentage.
max_revisions_to_retain47Nombre maximal de révisions Cloud Run à conserver. Définissez 0 pour désactiver.
service_annotations4{}Annotations Cloud Run avancées.
service_labels4{}Étiquettes appliquées au service Cloud Run.

Différences par rapport aux valeurs par défaut de App CloudRun :

VariableApp CloudRunPaperless CloudRunRaison
container_port80808000Paperless-ngx gunicorn écoute sur 8000.
cpu_limit'1000m''2000m'L'OCR avec Tesseract est gourmand en CPU ; 2 vCPU recommandés.
memory_limit'512Mi''2Gi'Paperless-ngx charge les miniatures de documents et les modèles ML en mémoire.
enable_image_mirroringfalsetrueMet en miroir depuis GHCR pour éviter les limites de débit et prendre en charge Binary Authorization.

B. Base de données (Cloud SQL — PostgreSQL 15)​

Paperless-ngx nécessite PostgreSQL. Paperless Common fixe database_type = "POSTGRES_15" et configure les variables de connexion en conséquence. MySQL et SQLite ne sont pas pris en charge.

Connexion par socket Unix : enable_cloudsql_volume par défaut true. App CloudRun injecte le sidecar Auth Proxy et définit DB_HOST sur le chemin du socket sous /cloudsql.

VariableGroupeValeur par défautDescription
database_type12'POSTGRES_15'PostgreSQL 15. Ne pas modifier — Paperless-ngx nécessite PostgreSQL.
db_name12'paperless'Nom de la base de données PostgreSQL. Ne pas modifier après le déploiement initial.
db_user12'paperless'Utilisateur de l'application PostgreSQL. Mot de passe généré automatiquement et stocké dans Secret Manager.
database_password_length1232Longueur du mot de passe généré automatiquement. Plage : 16–64.
enable_auto_password_rotation12falseRotation automatisée du mot de passe sans interruption de service.
rotation_propagation_delay_sec1290Secondes à attendre après la rotation avant de redémarrer le service.

C. Stockage (GCS Fuse)​

GCS Fuse est le mécanisme de stockage persistant principal. Contrairement à Ghost (qui repose sur NFS pour le contenu), Paperless-ngx stocke tous les documents traités, les miniatures et les originaux dans un bucket monté via GCS FUSE à /usr/src/paperless/media. Cette conception rend Paperless-ngx bien adapté à Cloud Run — les documents survivent au recyclage des instances et à la mise à l'échelle à zéro car ils se trouvent dans GCS, et non sur le disque local.

Volume GCS Fuse par défaut : Lorsque gcs_volumes = [] (la valeur par défaut), Paperless Common provisionne automatiquement un bucket GCS paperless-media et le monte à /usr/src/paperless/media avec les options implicit-dirs, stat-cache-ttl=60s et type-cache-ttl=60s. GCS Fuse nécessite execution_environment = 'gen2'.

NFS est également activé par défaut (enable_nfs = true). L'adresse IP du serveur NFS est utilisée comme hôte Redis lorsqu'aucun redis_host n'est explicitement configuré. NFS fournit également une solution de repli de système de fichiers local pour le répertoire de consommation si nécessaire. Nécessite execution_environment = 'gen2'.

VariableGroupeValeur par défautDescription
gcs_volumes11[]Buckets GCS à monter via GCS Fuse. Lorsqu'il est vide, Paperless Common monte automatiquement le bucket paperless-media à /usr/src/paperless/media. Nécessite gen2.
create_cloud_storage11trueDéfinissez false pour ignorer la création de buckets GCS supplémentaires.
storage_buckets11[]Buckets GCS supplémentaires au-delà du bucket média auto-provisionné.
enable_nfs11trueProvisionne le serveur NFS. Utilisé comme hôte Redis lorsque redis_host est vide. Nécessite gen2.
nfs_mount_path11'/mnt/nfs'Chemin du conteneur pour le montage NFS.
nfs_instance_name11""Nom d'une VM GCE NFS existante. Laissez vide pour la découvrir automatiquement ou la provisionner en ligne.
nfs_instance_base_name11'app-nfs'Nom de base pour une VM GCE NFS en ligne. L'ID de déploiement est ajouté.
manage_storage_kms_iam11falseCrée un trousseau de clés KMS CMEK et active CMEK sur tous les buckets de stockage.
enable_artifact_registry_cmek11falseCrée une clé KMS Artifact Registry pour le chiffrement des images au repos.

D. Réseau​

VariableGroupeValeur par défautDescription
ingress_settings5'all''all' — internet public ; 'internal' — VPC uniquement ; 'internal-and-cloud-load-balancing' — force le trafic via l'équilibreur de charge HTTPS.
vpc_egress_setting5'PRIVATE_RANGES_ONLY''PRIVATE_RANGES_ONLY' achemine uniquement le trafic RFC 1918 via VPC. 'ALL_TRAFFIC' achemine tout le trafic sortant via VPC.

E. Initialisation et amorçage​

Un job Cloud Run db-init est automatiquement provisionné par Paperless Common lorsque initialization_jobs est laissé comme liste vide par défaut ([]). Il utilise une image client PostgreSQL et exécute Paperless_Common/scripts/db-init.sh, qui effectue les opérations idempotentes suivantes :

  1. Se connecte à Cloud SQL PostgreSQL via le socket Unix du proxy d'authentification.
  2. Crée l'utilisateur de base de données paperless avec le mot de passe de Secret Manager.
  3. Crée la base de données paperless si elle n'existe pas.
  4. Accorde à l'utilisateur de l'application tous les privilèges sur la base de données.

Remplacez initialization_jobs par une liste non vide pour remplacer cette valeur par défaut par des jobs personnalisés. Lorsque initialization_jobs est non vide, Paperless Common n'injecte pas le job db-init par défaut.

Des jobs cron récurrents supplémentaires et des services Cloud Run sidecar supplémentaires (par exemple, Gotenberg pour la conversion de documents bureautiques, Tika pour l'extraction de contenu) peuvent être configurés via cron_jobs et additional_services :

VariableGroupeValeur par défautDescription
initialization_jobs13[]Jobs Cloud Run ponctuels. Laissez vide pour que Paperless Common fournisse le job db-init par défaut.
cron_jobs13[]Jobs récurrents déclenchés par Cloud Scheduler.
additional_services13[]Services Cloud Run supplémentaires déployés aux côtés de Paperless-ngx. Utilisez-les pour ajouter Gotenberg ou Tika.

4. Sécurité avancée​

A. Cloud Armor WAF​

Lorsque enable_cloud_armor = true, un équilibreur de charge HTTPS global avec une politique Cloud Armor WAF (OWASP Top 10, DDoS adaptatif, limitation de débit à 500 requêtes/min) est provisionné devant Cloud Run. Les systèmes de gestion de documents contenant des fichiers sensibles sont de bons candidats pour la protection WAF.

VariableGroupeValeur par défautDescription
enable_cloud_armor10falseProvisionne l'équilibreur de charge HTTPS global + Cloud Armor WAF. Requis pour les domaines personnalisés, le CDN et la protection DDoS.
admin_ip_ranges10[]Plages CIDR exemptées des règles WAF (par exemple, VPN de bureau).

B. Proxy conscient de l'identité (IAP)​

Lorsque enable_iap = true, l'intégration IAP native de Cloud Run est activée directement sur le service. L'authentification par identité Google est requise avant que les requêtes n'atteignent Paperless-ngx. Recommandé pour les archives de documents internes où l'accès doit être restreint aux utilisateurs organisationnels authentifiés.

VariableGroupeValeur par défautDescription
enable_iap5falseActive IAP nativement sur le service Cloud Run.
iap_authorized_users5[]Utilisateurs/comptes de service autorisés. Format : 'user:email' ou 'serviceAccount:sa@...'.
iap_authorized_groups5[]Groupes Google autorisés. Format : 'group:name@example.com'.

C. Autorisation binaire​

Lorsque enable_binary_authorization = true, Cloud Run impose que les images déployées portent une attestation cryptographique valide.

VariableGroupeValeur par défautDescription
enable_binary_authorization8falseApplique l'attestation d'image. Nécessite une politique d'autorisation binaire et un attestateur préconfigurés dans le projet.

D. Contrôles de service VPC​

Lorsque enable_vpc_sc = true, tous les appels d'API GCP de ce module sont liés à un périmètre VPC-SC existant.

VariableGroupeValeur par défautDescription
enable_vpc_sc22falseEnregistre les appels d'API du module dans le périmètre VPC-SC du projet. Un périmètre doit déjà exister avant l'activation.

E. Intégration de Secret Manager​

Les secrets d'application Paperless-ngx sont stockés dans Secret Manager et injectés nativement par Cloud Run au démarrage de la révision — le texte en clair n'est jamais écrit dans l'état Terraform.

Paperless Common génère automatiquement PAPERLESS_ADMIN_PASSWORD et PAPERLESS_SECRET_KEY. Des secrets définis par l'utilisateur peuvent être ajoutés via secret_environment_variables.

VariableGroupeValeur par défautDescription
secret_environment_variables6{}Mappage du nom de la variable d'environnement → ID du secret Secret Manager. Résolu à l'exécution.
secret_rotation_period6'2592000s'Fréquence à laquelle Secret Manager émet des notifications de rotation. Par défaut : 30 jours.
secret_propagation_delay630Secondes à attendre après la création du secret avant que les ressources dépendantes ne continuent.

5. Trafic et entrée​

A. Équilibreur de charge HTTPS​

Lorsque enable_cloud_armor = true, un équilibreur de charge HTTPS global adossé à un NEG sans serveur est provisionné. Le trafic circule : Internet → Cloud Armor → Équilibreur de charge HTTPS global → NEG sans serveur → Cloud Run.

Le réglage ingress_settings = 'internal-and-cloud-load-balancing' force tout le trafic Paperless-ngx à passer par l'équilibreur de charge, empêchant l'accès direct par URL *.run.app.

B. Cloud CDN​

Lorsque enable_cdn = true (nécessite enable_cloud_armor = true), Cloud CDN est attaché au backend de l'équilibreur de charge HTTPS.

Considération Paperless-ngx : Paperless-ngx sert principalement du contenu authentifié et spécifique à l'utilisateur (listes de documents, aperçus, liens de téléchargement). La mise en cache CDN est la plus bénéfique pour les actifs statiques (CSS, JS, miniatures). Assurez-vous que les réponses de documents authentifiés incluent les en-têtes Cache-Control: private avant d'activer le CDN pour éviter l'empoisonnement du cache entre utilisateurs.

VariableGroupeValeur par défautDescription
enable_cdn10falseActive Cloud CDN sur le backend de l'équilibreur de charge HTTPS. N'est efficace que lorsque enable_cloud_armor = true.
max_images_to_retain107Nombre maximal d'images de conteneurs récentes à conserver dans Artifact Registry. Définissez 0 pour désactiver.
delete_untagged_images10trueSupprime automatiquement les images non taguées d'Artifact Registry.
image_retention_days1030Jours après lesquels les images sont éligibles à la suppression.

C. Domaines personnalisés​

VariableGroupeValeur par défautDescription
application_domains10[]Noms de domaine personnalisés pour l'équilibreur de charge HTTPS. Certificats SSL gérés par Google provisionnés par domaine.

Après le premier apply, récupérez l'IP de l'équilibreur de charge à partir de la sortie Terraform load_balancer_ip et créez un enregistrement A. Le provisionnement du certificat SSL prend 10 à 30 minutes après la propagation DNS.


6. CI/CD et livraison​

A. Déclencheurs Cloud Build​

Lorsque enable_cicd_trigger = true, une connexion GitHub Cloud Build et un déclencheur de push sont provisionnés. Le déclencheur construit et déploie une image Paperless-ngx personnalisée lorsque du code est poussé vers la branche configurée.

VariableGroupeValeur par défautDescription
enable_cicd_trigger8falseProvisionne un déclencheur GitHub Cloud Build.
github_repository_url8""URL HTTPS complète du dépôt GitHub.
github_token8""PAT GitHub. Requis lors du premier apply. Sensible.
github_app_installation_id8""ID d'installation de l'application GitHub (préféré pour les dépôts d'organisation).
cicd_trigger_config8{ branch_pattern = "^main$" }Configuration avancée du déclencheur : branch_pattern, included_files, ignored_files, trigger_name, substitutions.

B. Pipeline Cloud Deploy​

Lorsque enable_cloud_deploy = true (nécessite enable_cicd_trigger = true), le pipeline CI/CD est mis à niveau vers un pipeline de livraison Cloud Deploy géré avec des étapes de promotion séquentielles.

VariableGroupeValeur par défautDescription
enable_cloud_deploy8falseProvisionne un pipeline Cloud Deploy. Nécessite enable_cicd_trigger = true.
cloud_deploy_stages8[dev, staging, prod(approval)]Étapes de promotion ordonnées. Chacune : name, target_name, service_name, require_approval, auto_promote.

7. Fiabilité et planification​

A. Mise à l'échelle et concurrence​

min_instance_count = 0 et max_instance_count = 3 sont configurables via des variables (contrairement aux valeurs codées en dur de Ghost). Les tâches OCR de Paperless-ngx s'exécutent de manière asynchrone via des workers Celery adossés à Redis — l'interface utilisateur web reste réactive pendant les jobs OCR lourds. Plusieurs instances Cloud Run peuvent s'exécuter simultanément avec des documents stockés dans GCS.

Remarque sur le pipeline de consommation : Le pipeline de consommation de documents en arrière-plan nécessite au moins une instance en cours d'exécution. Le réglage de min_instance_count = 0 signifie que les documents téléchargés ne seront pas traités avant que la prochaine requête ne réchauffe l'instance.

B. Répartition du trafic​

VariableGroupeValeur par défautDescription
traffic_split4[]Allocation de trafic basée sur un pourcentage entre les révisions nommées. Toutes les entrées doivent totaliser 100. Vide envoie 100 % à la dernière révision.

C. Sondes de santé et surveillance de la disponibilité​

Les sondes de démarrage et de vivacité ciblent / (la page de connexion de Paperless-ngx), qui renvoie HTTP 200 lorsque l'application est entièrement initialisée. Paperless-ngx effectue des migrations de base de données et démarre les workers Celery au premier démarrage — la sonde de démarrage autorise 60 secondes de délai initial avec 60 seuils d'échec avant d'abandonner.

VariableGroupeValeur par défautDescription
startup_probe14{ enabled=true, type="HTTP", path="/", initial_delay_seconds=60, timeout_seconds=10, period_seconds=10, failure_threshold=60 }Sonde de démarrage. 60 × 10s = 600s d'allocation totale pour le premier démarrage.
liveness_probe14{ enabled=true, type="HTTP", path="/", initial_delay_seconds=60, timeout_seconds=10, period_seconds=30, failure_threshold=3 }Sonde de vivacité. Le conteneur est redémarré après 3 échecs consécutifs.
uptime_check_config14{ enabled=false, path="/" }Test de disponibilité Cloud Monitoring facultatif. Les alertes notifient support_users si inaccessible.
alert_policies14[]Politiques d'alerte métrique Cloud Monitoring.

D. Rotation automatique des mots de passe​

Lorsque enable_auto_password_rotation = true, un pipeline de rotation de mot de passe sans interruption de service est provisionné :

  1. Secret Manager émet une notification de rotation à chaque intervalle de secret_rotation_period.
  2. Eventarc déclenche un job de rotation Cloud Run.
  3. Le job génère un nouveau mot de passe, met à jour l'utilisateur Cloud SQL PostgreSQL et écrit une nouvelle version du secret.
  4. Après rotation_propagation_delay_sec secondes, le job redémarre le service Paperless-ngx.
VariableGroupeValeur par défautDescription
enable_auto_password_rotation12falseActive la rotation automatisée des mots de passe.
rotation_propagation_delay_sec1290Secondes à attendre après l'écriture du nouveau secret avant de redémarrer.

8. Intégrations​

A. Redis (obligatoire)​

Redis est obligatoire et activé par défaut (enable_redis = true). Paperless-ngx utilise Redis comme courtier de messages Celery — le traitement OCR en arrière-plan, la classification des documents, les tâches du pipeline de consommation et les appels API asynchrones dépendent tous de Redis. Paperless-ngx ne démarrera pas sans une instance Redis accessible.

Lorsque enable_redis = true et redis_host n'est pas fourni, le module utilise par défaut l'IP du serveur NFS comme hôte Redis (une instance Redis légère co-localisée sur la VM GCE NFS). Pour les déploiements de production, pointez redis_host vers une instance Google Cloud Memorystore for Redis dédiée.

VariableGroupeValeur par défautDescription
enable_redis21trueObligatoire. Redis pour la file d'attente des tâches Celery et le backend de résultats.
redis_host21""Nom d'hôte ou IP du serveur Redis. Par défaut, l'IP du serveur NFS si vide. À remplacer par Memorystore pour la production.
redis_port21'6379'Port TCP du serveur Redis (chaîne).
redis_auth21""Mot de passe d'authentification Redis. Laisser vide si Redis ne nécessite pas d'authentification. Sensible.

B. Paramètres de l'application Paperless-ngx​

Paperless-ngx expose plusieurs paramètres au niveau de l'application en tant que variables de premier ordre. Celles-ci sont injectées en tant que variables d'environnement par Paperless Common.

VariableGroupeValeur par défautDescription
time_zone15'UTC'Fuseau horaire pour les horodatages des documents et les tâches planifiées. Important pour une analyse correcte des dates pendant l'OCR. Utilisez un identifiant TZ valide (par exemple, 'Europe/London', 'America/New_York').
ocr_language15'eng'Code de langue OCR Tesseract. Combinez plusieurs avec + (par exemple, 'eng+deu+fra'). Les packs de langue doivent être installés dans l'image du conteneur.
admin_user15'admin'Nom d'utilisateur du superutilisateur auto-créé au premier démarrage.
admin_email15'admin@example.com'E-mail du compte superutilisateur auto-créé.

Codes de langue OCR : Utilisez les codes ISO 639-2/T tels qu'utilisés par Tesseract. Valeurs courantes : eng (anglais), deu (allemand), fra (français), spa (espagnol), ita (italien), nld (néerlandais), por (portugais). Le pack de langue doit être présent dans le conteneur — l'image par défaut inclut un ensemble standard ; les builds personnalisés peuvent ajouter des packs supplémentaires.

C. Tika et Gotenberg (facultatif)​

Paperless-ngx s'intègre facultativement avec Tika (Apache) pour l'extraction de contenu à partir de documents bureautiques et Gotenberg pour la conversion de formats de documents. Ceux-ci sont désactivés par défaut (PAPERLESS_TIKA_ENABLED=false).

Pour les activer, ajoutez-les comme services Cloud Run supplémentaires via additional_services et définissez PAPERLESS_TIKA_ENABLED=true dans environment_variables :

additional_services = [
{
name = "gotenberg"
image = "gotenberg/gotenberg:8"
port = 3000
cpu_limit = "1000m"
memory_limit = "512Mi"
ingress = "INGRESS_TRAFFIC_ALL"
output_env_var_name = "PAPERLESS_TIKA_GOTENBERG_ENDPOINT"
},
{
name = "tika"
image = "apache/tika:latest"
port = 9998
cpu_limit = "1000m"
memory_limit = "512Mi"
ingress = "INGRESS_TRAFFIC_ALL"
output_env_var_name = "PAPERLESS_TIKA_ENDPOINT"
}
]

environment_variables = {
PAPERLESS_TIKA_ENABLED = "true"
}

D. Importation et récupération de sauvegarde​

Lorsque enable_backup_import = true, un job Cloud Run dédié restaure une sauvegarde de base de données existante dans l'instance Cloud SQL PostgreSQL provisionnée. Cela s'exécute après le job db-init.

VariableGroupeValeur par défautDescription
backup_schedule7'0 2 * * *'Expression Cron (UTC) pour les sauvegardes quotidiennes automatisées.
backup_retention_days77Jours de rétention des fichiers de sauvegarde dans GCS.
enable_backup_import7falseDéclenche une restauration unique lors de l'apply. Définissez false après une importation réussie.
backup_source7'gcs''gcs' (URI GCS complet) ou 'gdrive' (ID de fichier Drive).
backup_uri7""URI GCS complet (par exemple, 'gs://my-bucket/paperless-backup.sql') ou ID de fichier Google Drive.
backup_format7'sql'Format de sauvegarde. Options : sql, tar, gz, tgz, tar.gz, zip.

E. Observabilité et alertes​

Un test de disponibilité Cloud Monitoring interroge le point de terminaison Paperless-ngx depuis plusieurs emplacements mondiaux. Des politiques d'alerte personnalisées peuvent surveiller les métriques Cloud Run (latence, taux d'erreur, nombre d'instances) et notifier support_users.

VariableGroupeValeur par défautDescription
uptime_check_config14{ enabled=false, path="/" }Configuration du test de disponibilité. Désactivé par défaut.
alert_policies14[]Politiques d'alerte métrique. Chacune : name, metric_type, comparison, threshold_value, duration_seconds, aggregation_period.

9. Exploration avec la console GCP​

Après un déploiement réussi, les zones suivantes de la console GCP fournissent le plus d'informations sur une instance Paperless-ngx en cours d'exécution.

Cloud Run — Détails du service Accédez à Cloud Run → Services → paperless-<deployment-id>. L'onglet Revisions affiche toutes les révisions déployées, leur pourcentage de trafic et le tag de l'image du conteneur. Cliquez sur une révision pour voir ses variables d'environnement (masquées pour les secrets) et ses limites de ressources. L'onglet Logs diffuse les sorties stdout/stderr combinées du serveur gunicorn et du worker Celery.

Cloud Run — URL du service Le champ URL dans la vue d'ensemble du service est l'adresse *.run.app directe de Paperless-ngx. Ouvrez-la dans un navigateur pour accéder à la page de connexion. Connectez-vous avec le nom d'utilisateur admin_user et le mot de passe récupéré de Secret Manager (voir §11).

Secret Manager Accédez à Security → Secret Manager. Filtrez par le préfixe application_name. Vous verrez :

  • paperless-admin-password-<deployment-id> — le mot de passe administrateur initial.
  • paperless-secret-key-<deployment-id> — la clé secrète de l'application Django.
  • paperless-db-password-<deployment-id> — le mot de passe de l'utilisateur de l'application PostgreSQL.

Cliquez sur n'importe quel secret et sélectionnez View secret value (dernière version) pour récupérer l'identifiant.

Cloud SQL Accédez à SQL → Instances. L'instance Paperless-ngx est nommée app<name><tenant><id> suivant la convention de nommage du dépôt. Cliquez sur l'instance, puis :

  • Onglet Databases : confirme que la base de données paperless a été créée par db-init.
  • Onglet Users : confirme que l'utilisateur paperless a été créé.
  • Onglet Connections : affiche les connexions actives du sidecar Cloud Run Auth Proxy.
  • Onglet Operations : affiche l'historique de toutes les opérations Cloud SQL, y compris la création de bases de données et d'utilisateurs.

Cloud Storage Accédez à Cloud Storage → Buckets. Le bucket paperless-media-<deployment-id> contient toutes les données de document persistantes : PDF traités, originaux, miniatures et texte extrait par OCR. Parcourez le bucket pour vérifier que les documents sont stockés. Le bucket utilise la classe de stockage STANDARD avec la prévention de l'accès public appliquée.

Artifact Registry Accédez à Artifact Registry → Repositories. Le dépôt paperless stocke l'image conteneur Paperless-ngx personnalisée. L'onglet Images affiche les versions taguées avec les horodatages et les hachages de digest.

Cloud Monitoring — Tests de disponibilité Accédez à Monitoring → Uptime checks. Le test de disponibilité pour la page de connexion Paperless-ngx affiche la disponibilité sur les emplacements de vérification mondiaux et les temps de réponse. Les échecs ici alertent support_users par e-mail.

Cloud Build Accédez à Cloud Build → History. Chaque exécution de déploiement apparaît ici avec les logs de build. L'exécution du job Cloud Run db-init est déclenchée dans le cadre du pipeline d'apply.


10. Exploration avec gcloud​

Les commandes suivantes sont utiles pour inspecter et opérer un déploiement Cloud Run Paperless-ngx. Remplacez PROJECT_ID, REGION et DEPLOYMENT_ID par vos valeurs.

# List all Cloud Run services in the project
gcloud run services list \
--project=PROJECT_ID \
--region=REGION \
--format="table(name,status.url,status.latestReadyRevisionName,status.conditions[0].status)"

# Describe the Paperless-ngx service and show the current URL
gcloud run services describe paperless-DEPLOYMENT_ID \
--project=PROJECT_ID \
--region=REGION \
--format="value(status.url)"

# Stream live logs from the Paperless-ngx service (last 5 minutes)
gcloud logging read \
'resource.type="cloud_run_revision" AND resource.labels.service_name="paperless-DEPLOYMENT_ID"' \
--project=PROJECT_ID \
--freshness=5m \
--format="table(timestamp,textPayload)" \
--order=asc

# List all revisions of the Paperless-ngx service
gcloud run revisions list \
--project=PROJECT_ID \
--region=REGION \
--service=paperless-DEPLOYMENT_ID \
--format="table(name,status.conditions[0].status,spec.containers[0].image,metadata.creationTimestamp)"

# Get the admin password from Secret Manager
gcloud secrets versions access latest \
--secret="paperless-admin-password-DEPLOYMENT_ID" \
--project=PROJECT_ID

# Get the Django secret key from Secret Manager
gcloud secrets versions access latest \
--secret="paperless-secret-key-DEPLOYMENT_ID" \
--project=PROJECT_ID

# List all secrets created for this deployment
gcloud secrets list \
--project=PROJECT_ID \
--filter="name:paperless" \
--format="table(name,replication.automatic,createTime)"

# Describe the Cloud SQL instance
gcloud sql instances describe APP_SQL_INSTANCE_NAME \
--project=PROJECT_ID \
--format="table(name,databaseVersion,settings.tier,ipAddresses[0].ipAddress,state)"

# List databases on the Cloud SQL instance
gcloud sql databases list \
--instance=APP_SQL_INSTANCE_NAME \
--project=PROJECT_ID

# List Cloud SQL users
gcloud sql users list \
--instance=APP_SQL_INSTANCE_NAME \
--project=PROJECT_ID

# List GCS buckets for the deployment (filter by name prefix)
gcloud storage buckets list \
--project=PROJECT_ID \
--filter="name:paperless" \
--format="table(name,location,storageClass,timeCreated)"

# List objects in the paperless-media bucket (document store)
gcloud storage ls gs://paperless-media-DEPLOYMENT_ID/

# List objects in the media/documents directory
gcloud storage ls gs://paperless-media-DEPLOYMENT_ID/documents/

# Check Memorystore Redis instance (if using dedicated Redis)
gcloud redis instances list \
--region=REGION \
--project=PROJECT_ID \
--format="table(name,host,port,state,memorySizeGb,authEnabled)"

# List Cloud Run Jobs (db-init and any custom jobs)
gcloud run jobs list \
--project=PROJECT_ID \
--region=REGION \
--format="table(name,status.latestCreatedExecution.name,metadata.creationTimestamp)"

# Execute the db-init job manually (e.g., for re-initialisation)
gcloud run jobs execute paperless-db-init-DEPLOYMENT_ID \
--project=PROJECT_ID \
--region=REGION

# Get the execution status of a Cloud Run Job
gcloud run jobs executions list \
--job=paperless-db-init-DEPLOYMENT_ID \
--project=PROJECT_ID \
--region=REGION \
--format="table(name,completionStatus,startTime,completionTime)"

# Check Cloud Monitoring uptime check results
gcloud monitoring uptime list-configs \
--project=PROJECT_ID \
--format="table(displayName,httpCheck.path,period,timeout)"

# List Artifact Registry images for the paperless repository
gcloud artifacts docker images list REGION-docker.pkg.dev/PROJECT_ID/paperless \
--project=PROJECT_ID \
--format="table(package,version,tags,createTime)"

# Update the Cloud Run service's traffic to a specific revision (canary)
gcloud run services update-traffic paperless-DEPLOYMENT_ID \
--project=PROJECT_ID \
--region=REGION \
--to-revisions=paperless-DEPLOYMENT_ID-REVISION=10,LATEST=90

# Send all traffic back to latest
gcloud run services update-traffic paperless-DEPLOYMENT_ID \
--project=PROJECT_ID \
--region=REGION \
--to-latest

# Check IAM bindings on the Cloud Run service
gcloud run services get-iam-policy paperless-DEPLOYMENT_ID \
--project=PROJECT_ID \
--region=REGION

11. Comportements gérés par la plateforme​

Les comportements suivants sont appliqués automatiquement par Paperless CloudRun, quelles que soient les valeurs des variables.

ComportementImplémentationDétail
PostgreSQL 15 requisdatabase_type = "POSTGRES_15" défini par Paperless CommonPaperless-ngx nécessite PostgreSQL. MySQL et SQLite ne sont pas pris en charge.
Mot de passe administrateur auto-généréSecret PAPERLESS_ADMIN_PASSWORD provisionné par Paperless CommonLe mot de passe administrateur initial est stocké dans Secret Manager. Récupérez-le via gcloud secrets versions access latest --secret=paperless-admin-password-<id>.
Clé secrète Django auto-généréeSecret PAPERLESS_SECRET_KEY provisionné par Paperless CommonRequis pour la signature de session Django. La régénération de cette clé invalide toutes les sessions utilisateur existantes.
GCS Fuse auto-montéBucket paperless-media monté à /usr/src/paperless/mediaLorsque gcs_volumes = [], Paperless Common provisionne et monte automatiquement le bucket média. Nécessite gen2.
Redis requisenable_redis = true par défautPaperless-ngx ne démarrera pas sans Redis. Lorsque redis_host = "", l'IP du serveur NFS est utilisée.
min_instance_count = 0, cpu_always_allocated = falsePar défaut dans variables.tf (mise à l'échelle à zéro, facturation basée sur les requêtes)Par défaut, le coût est prioritaire. Définissez à la fois cpu_always_allocated = true et min_instance_count = 1+ pour maintenir le pipeline de consommation actif sans délai de démarrage à froid — min_instance_count seul n'est pas suffisant.
Mise en miroir d'images activéeenable_image_mirroring = true par défautLes images GHCR sont mises en miroir vers Artifact Registry pour éviter les limites de débit et satisfaire les exigences d'autorisation binaire.
Job db-init par défautFourni par Paperless Common lorsque initialization_jobs = []La base de données et l'utilisateur PostgreSQL sont créés automatiquement. Remplacez par une liste non vide pour remplacer.
Répertoire des scriptsscripts_dir = abspath("${module.paperless_app.path}/scripts")Les scripts d'initialisation proviennent de Paperless Common, et non du répertoire de déploiement.

12. Référence des variables​

Toutes les variables configurables par l'utilisateur exposées par Paperless CloudRun, triées par groupe d'interface utilisateur.

VariableGroupeValeur par défautDescription
project_id1—ID du projet GCP. Obligatoire.
region1'us-central1'Région GCP pour le déploiement des ressources.
tenant_id2'demo'Suffixe court ajouté à tous les noms de ressources.
support_users2[]Adresses e-mail pour les alertes de surveillance.
resource_labels2{}Libellés appliqués à toutes les ressources provisionnées.
application_name3'paperless'Nom de ressource de base. Ne pas modifier après le déploiement initial.
display_name3'Paperless-ngx - Document Management System'Nom lisible par l'homme pour les tableaux de bord.
description3'Paperless-ngx - open-source document management system...'Description du service.
application_version3'latest'Tag de l'image du conteneur. Épingler à une version spécifique pour la production.
deploy_application4trueDéfinir false pour un déploiement uniquement d'infrastructure.
cpu_limit4'2000m'CPU par instance. 2 vCPU recommandés pour l'OCR.
memory_limit4'2Gi'Mémoire par instance.
cpu_always_allocated4falseValeur par défaut de démarrage à froid axée sur les coûts. Définissez true avec min_instance_count >= 1 pour restaurer le traitement continu du consommateur/OCR.
min_instance_count40Instances minimales. Mise à l'échelle à zéro par défaut ; définissez sur 1+ et cpu_always_allocated = true pour maintenir le pipeline de consommation actif.
max_instance_count43Instances maximales. Plafond de coût.
container_port48000Port gunicorn Paperless-ngx.
execution_environment4'gen2'Gen2 requis pour GCS Fuse.
timeout_seconds4300Durée maximale de la requête. Augmenter pour l'OCR de gros documents.
enable_cloudsql_volume4trueSe connecte via le socket Unix du proxy d'authentification Cloud SQL.
enable_image_mirroring4trueMet en miroir l'image GHCR vers Artifact Registry.
container_protocol4'http1''http1' ou 'h2c'.
traffic_split4[]Allocation de trafic Canary/blue-green.
max_revisions_to_retain47Nombre maximal de révisions Cloud Run à conserver.
cloudsql_volume_mount_path4'/cloudsql'Chemin du conteneur pour le socket Unix du proxy d'authentification.
service_annotations4{}Annotations Cloud Run avancées.
service_labels4{}Libellés appliqués au service Cloud Run.
ingress_settings5'all''all', 'internal', ou 'internal-and-cloud-load-balancing'.
vpc_egress_setting5'PRIVATE_RANGES_ONLY''PRIVATE_RANGES_ONLY' ou 'ALL_TRAFFIC'.
enable_iap5falseActive IAP nativement sur le service Cloud Run.
iap_authorized_users5[]Utilisateurs/SA ayant accès à IAP.
iap_authorized_groups5[]Groupes Google ayant accès à IAP.
environment_variables6{}Variables d'environnement en texte clair pour la configuration de Paperless-ngx.
secret_environment_variables6{}Références Secret Manager.
secret_propagation_delay630Secondes à attendre après la création du secret.
secret_rotation_period6'2592000s'Fréquence de notification de rotation de Secret Manager.
backup_schedule7'0 2 * * *'Expression Cron (UTC) pour les sauvegardes automatisées.
backup_retention_days77Jours de rétention des fichiers de sauvegarde dans GCS.
enable_backup_import7falseDéclenche une restauration unique lors de l'apply.
backup_source7'gcs''gcs' (URI complet) ou 'gdrive' (ID de fichier).
backup_uri7""URI GCS complet ou ID de fichier Google Drive.
backup_format7'sql'Format de sauvegarde. Options : sql, tar, gz, tgz, tar.gz, zip.
enable_cicd_trigger8falseProvisionne un déclencheur GitHub Cloud Build.
github_repository_url8""URL HTTPS complète du dépôt GitHub.
github_token8""PAT GitHub. Requis lors du premier apply. Sensible.
github_app_installation_id8""ID d'installation de l'application GitHub.
cicd_trigger_config8{ branch_pattern = "^main$" }Configuration avancée du déclencheur Cloud Build.
enable_cloud_deploy8falseProvisionne un pipeline de livraison progressive Cloud Deploy.
cloud_deploy_stages8[dev, staging, prod(approval)]Étapes de promotion Cloud Deploy ordonnées.
enable_binary_authorization8falseApplique l'attestation d'image lors du déploiement.
enable_custom_sql_scripts9falseExécute des scripts SQL depuis GCS après le provisionnement.
custom_sql_scripts_bucket9""Bucket GCS contenant les scripts SQL.
custom_sql_scripts_path9""Préfixe de chemin dans le bucket.
custom_sql_scripts_use_root9falseExécuter les scripts en tant qu'utilisateur root de la base de données.
enable_cloud_armor10falseProvisionne un équilibreur de charge HTTPS global + Cloud Armor WAF.
admin_ip_ranges10[]Plages CIDR exemptées des règles WAF.
application_domains10[]Domaines personnalisés avec certificats SSL gérés par Google.
enable_cdn10falseActive Cloud CDN sur le backend de l'équilibreur de charge HTTPS.
max_images_to_retain107Nombre maximal d'images conteneurs récentes dans Artifact Registry.
delete_untagged_images10trueSupprime les images non taguées d'Artifact Registry.
image_retention_days1030Jours après lesquels les images sont éligibles à la suppression.
create_cloud_storage11trueDéfinir false pour ignorer la création du bucket GCS.
storage_buckets11[]Buckets GCS supplémentaires à provisionner.
enable_nfs11trueProvisionne le serveur NFS. Utilisé comme hôte Redis lorsque redis_host est vide.
nfs_mount_path11'/mnt/nfs'Chemin du conteneur pour le montage NFS.
nfs_instance_name11""Nom de la VM GCE NFS existante. Laisser vide pour la découverte automatique.
nfs_instance_base_name11'app-nfs'Nom de base pour la VM NFS intégrée.
gcs_volumes11[]Montages de volume GCS Fuse. Le montage automatique de paperless-media à /usr/src/paperless/media est vide.
manage_storage_kms_iam11falseCrée une clé KMS CMEK pour les buckets de stockage.
enable_artifact_registry_cmek11falseCrée une clé KMS Artifact Registry.
database_type12'POSTGRES_15'Version PostgreSQL. Ne pas modifier — Paperless-ngx nécessite PostgreSQL.
db_name12'paperless'Nom de la base de données PostgreSQL. Ne pas modifier après le déploiement initial.
db_user12'paperless'Utilisateur de l'application PostgreSQL.
database_password_length1232Longueur du mot de passe auto-généré. Plage : 16–64.
enable_auto_password_rotation12falseRotation automatisée des mots de passe sans interruption de service.
rotation_propagation_delay_sec1290Secondes à attendre après la rotation avant de redémarrer.
initialization_jobs13[]Jobs Cloud Run ponctuels. Vide : Paperless Common fournit la valeur par défaut db-init.
cron_jobs13[]Jobs Cloud Run planifiés récurrents.
additional_services13[]Services Cloud Run supplémentaires (par exemple, Gotenberg, Tika).
startup_probe14{ path="/", initial_delay_seconds=60, failure_threshold=60, ... }Sonde de démarrage. Seuil d'échec long pour les migrations au premier démarrage.
liveness_probe14{ path="/", initial_delay_seconds=60, failure_threshold=3, ... }Sonde de vivacité.
uptime_check_config14{ enabled=false, path="/" }Test de disponibilité Cloud Monitoring facultatif.
alert_policies14[]Politiques d'alerte métrique Cloud Monitoring.
time_zone15'UTC'Fuseau horaire pour les horodatages des documents. Important pour l'analyse des dates OCR.
ocr_language15'eng'Langue OCR Tesseract. Combinez avec + pour plusieurs langues.
admin_user15'admin'Nom d'utilisateur du compte administrateur initial.
admin_email15'admin@example.com'E-mail du compte administrateur initial.
enable_redis21trueObligatoire. Redis pour la file d'attente des tâches Celery.
redis_host21""Nom d'hôte/IP Redis. Par défaut, l'IP du serveur NFS si vide.
redis_port21'6379'Port TCP Redis (chaîne).
redis_auth21""Mot de passe d'authentification Redis. Sensible.
enable_vpc_sc22falseEnregistre les appels API dans le périmètre VPC-SC du projet.
vpc_cidr_ranges22[]Plages CIDR de sous-réseau VPC pour le niveau d'accès réseau VPC-SC.
vpc_sc_dry_run22trueEnregistre les violations VPC-SC sans bloquer. Définissez false pour appliquer.
organization_id22""ID d'organisation GCP pour VPC-SC. Découvert automatiquement si vide.
enable_audit_logging22falseActive les journaux d'audit Cloud détaillés.

13. Sorties​

SortieDescription
service_nameNom du service Cloud Run.
service_urlURL publique du service Cloud Run.
service_locationRégion GCP où le service Cloud Run est déployé.
project_idID du projet GCP.
deployment_idSuffixe d'ID de déploiement utilisé dans les noms de ressources.
database_instance_nameNom de l'instance Cloud SQL PostgreSQL.
database_nameNom de la base de données de l'application.
database_userNom de l'utilisateur de la base de données de l'application.
database_password_secretNom du secret Secret Manager pour le mot de passe de la base de données.
storage_bucketsBuckets de stockage GCS créés.
load_balancer_ipAdresse IP statique de l'équilibreur de charge.
load_balancer_urlURL HTTPS pour accéder à l'application via l'équilibreur de charge.
container_imageImage conteneur utilisée pour le déploiement.
cicd_enabledIndique si le pipeline CI/CD est activé.
github_repository_urlURL du dépôt GitHub connecté pour le CI/CD.

Pièges de configuration et valeurs par défaut judicieuses​

Niveaux de risque : Critique (perte de données, panne totale, faille de sécurité) — Élevé (service indisponible ou dégradation significative) — Moyen (fonction dégradée ou coût accru) — Faible (impact mineur).

VariableValeur par défaut judicieuseRisqueConséquence d'une valeur incorrecte
project_id(obligatoire)CritiquePas de valeur par défaut — le déploiement échoue immédiatement.
database_type"POSTGRES_15"CritiquePaperless-ngx nécessite PostgreSQL. Changer pour MySQL ou NONE entraînera un échec de démarrage — l'ORM de Paperless-ngx est configuré exclusivement pour PostgreSQL.
enable_redistrueCritiqueRedis est obligatoire. Sans Redis, Paperless-ngx ne peut pas démarrer ses workers Celery — le pipeline de consommation, le traitement OCR et la classification des documents sont tous inopérants. Les documents téléchargés via l'interface utilisateur web seront mis en file d'attente indéfiniment.
redis_host"" (résolution automatique vers l'IP NFS)ÉlevéS'appuie sur l'IP du serveur NFS si vide. Si enable_nfs = false et redis_host reste vide avec enable_redis = true, Paperless-ngx ne parviendra pas à se connecter à Redis au démarrage.
enable_nfstrueÉlevéL'IP du serveur NFS est utilisée comme hôte Redis par défaut. La désactivation de NFS sans fournir un redis_host explicite entraîne des échecs de connexion Redis au démarrage.
execution_environment'gen2'CritiqueGCS Fuse nécessite Gen2. Passer à 'gen1' alors que les volumes GCS sont montés entraîne l'échec du démarrage des révisions Cloud Run. Le volume GCS Fuse paperless-media est toujours monté lorsque gcs_volumes = [].
gcs_volumes[] (montage automatique de paperless-media)CritiqueLe bucket paperless-media est le seul stockage persistant pour tous les documents Paperless-ngx. Si le montage automatique est incorrectement remplacé, les documents sont écrits dans le système de fichiers éphémère du conteneur et perdus lors du prochain déploiement de révision ou redémarrage d'instance.
min_instance_count0 (par défaut ; mise à l'échelle à zéro)ÉlevéLorsque l'instance est froide, les documents téléchargés ne sont pas consommés avant que la prochaine requête ne réchauffe le service. Pour les workflows de répertoire de consommation sans surveillance, cela peut entraîner des heures de documents non traités — définissez sur 1+ si cela est important.
cpu_always_allocatedfalse (par défaut ; facturation basée sur les requêtes)ÉlevéMême avec min_instance_count >= 1, la facturation basée sur les requêtes limite le CPU à près de zéro entre les requêtes, de sorte que le consommateur de documents + le worker OCR s'arrêtent effectivement. Définissez true avec min_instance_count >= 1 pour restaurer entièrement le traitement en arrière-plan continu.
db_name"paperless"CritiqueImmuable après le premier déploiement — la modification de cette valeur entraîne la recréation de la base de données par Terraform, détruisant toutes les métadonnées de document, les tags, les correspondants et les paramètres. Les fichiers de documents physiques dans GCS survivent mais deviennent non référencés.
db_user"paperless"CritiqueImmuable après le premier déploiement — la modification de cette valeur recrée l'utilisateur Cloud SQL et invalide toutes les informations d'identification stockées.
application_version"latest"MoyenL'utilisation de latest signifie que chaque exécution de Cloud Build peut extraire une nouvelle version de Paperless-ngx, ce qui peut inclure des migrations de base de données ou des changements incompatibles. Épinglez à une version spécifique (par exemple, "2.13.5") pour les déploiements de production.
ocr_language"eng"MoyenDéfinir pour correspondre à la langue principale des documents numérisés. Des codes de langue incorrects entraînent une mauvaise qualité d'OCR et des échecs d'indexation plein texte. Plusieurs langues ("eng+deu") augmentent le temps d'OCR.
time_zone"UTC"MoyenUn fuseau horaire incorrect entraîne des erreurs d'analyse de date de document pendant l'OCR — les dates sur les documents numérisés peuvent être attribuées au mauvais jour. Définissez pour correspondre au fuseau horaire de votre organisation.
memory_limit"2Gi"ÉlevéL'OCR sur des numérisations multipages à haute résolution nécessite une mémoire significative. Réduire en dessous de 1Gi provoque des erreurs OOM Python pendant le traitement Tesseract. Pour les charges de travail OCR lourdes, 4Gi est recommandé.
timeout_seconds300MoyenL'OCR sur de grands PDF multipages peut prendre plus de 300 secondes. Cloud Run mettra fin aux requêtes dépassant timeout_seconds. Envisagez de définir 600 ou plus pour les archives contenant de grands lots de documents.
backup_retention_days7MoyenSept jours sont insuffisants pour une archive de documents. La perte de plus de 7 jours de modifications de la base de données signifie la perte de toutes les métadonnées de document (tags, correspondants, champs personnalisés, notes) ajoutées pendant cette période. Augmentez à 30+ jours pour la production.
enable_cloud_armorfalseMoyenSans Cloud Armor, la page de connexion Paperless-ngx est exposée directement à Internet. Les systèmes de gestion de documents contiennent souvent des documents financiers et personnels sensibles. La protection WAF est fortement recommandée pour tout déploiement accessible via Internet.
enable_iapfalseMoyenIAP ajoute une authentification basée sur l'identité Google devant Paperless-ngx. Pour les archives de documents internes, IAP empêche entièrement les attaques par force brute contre la page de connexion Paperless-ngx.
startup_probe failure_threshold60ÉlevéPaperless-ngx applique les migrations de base de données au démarrage. 60 × 10s = 600 secondes de tolérance de démarrage totale. Réduire failure_threshold en dessous de 30 entraîne l'arrêt du conteneur par Cloud Run avant la fin des migrations lors du premier déploiement, créant une boucle de redémarrage.

Destruction des ressources​

Problème de suppression connu : libération de l'adresse IPv4 sans serveur​

Lors de la destruction d'un déploiement Cloud Run, vous pouvez rencontrer une erreur similaire à :

Error: Error waiting for Subnetwork to be deleted: The following serverless IPv4 address(es) on subnet ... are still in use.

Cause : GCP conserve les adresses IPv4 sans serveur sur le sous-réseau VPC de manière asynchrone après la suppression d'un service Cloud Run. Ces adresses sont libérées par GCP environ 20 à 30 minutes après la suppression du service Cloud Run.

Résolution : Attendez 20 à 30 minutes après la tentative de destruction initiale, puis exécutez à nouveau la commande de destruction :

tofu destroy

La deuxième exécution réussira une fois que GCP aura libéré les adresses réservées.

Need RAD to do something it does not do yet? Request it on the roadmap, or vote on what is already there.