Alfresco¶

Alfresco est la GED (gestion électronique de documents) de l'ADEME, en édition Enterprise. Elle est déployée sur les clusters Kubernetes à partir de Helm charts maintenus par nos soins, et son cycle de vie est piloté par ArgoCD selon un modèle app-of-apps.


Édition	Enterprise
Version en service	7.2
Environnements	intégration, recette, préproduction (cluster horsprod) et production (cluster prod)
Déploiements	`alfresco` (courant) et `alfresco26` (validation de la v26, temporaire)
Charts	`argocd-ademe-appofapps/charts/alfresco` et `.../alfresco26`
Values applicatives	dépôt `alfresco-cd` (maintenu par BlueXML)
Base de données	RDB Scaleway (PostgreSQL managé)
Authentification	Keycloak
Licence	embarquée dans l'image fournie par BlueXML

À qui s'adresse cette page

Cette page est destinée à l'équipe infra. L'exploitation applicative d'Alfresco et le déclenchement des déploiements relèvent de BlueXML : l'équipe infra fournit et maintient le socle — clusters, charts, values d'environnement, ArgoCD, base de données — et n'intervient dans le périmètre applicatif que sur sollicitation de BlueXML (voir Les values et ArgoCD). Ce partage explique pourquoi cette page documente en détail la mécanique de déploiement, et pas le fonctionnel de la GED.

La licence Enterprise relève également de BlueXML : elle est embarquée dans l'image qu'il fournit, et son échéance n'est pas à surveiller côté infra.

Accès¶

Trois points d'entrée par environnement, servis sous le même hôte :

	Repository / API	Digital Workspace	Share
Intégration	`https://int-alfresco.horsprod.ademe-scw.fr/`	`…/adw`	`…/share`
Recette	`https://rec-alfresco.horsprod.ademe-scw.fr/`	`…/adw`	`…/share`
Préproduction	`https://preprod-alfresco.horsprod.ademe-scw.fr/`	`…/adw`	`…/share`
Production	`https://alfresco.ademe.fr/`	`…/adw`	`…/share`

Les déploiements alfresco26 suivent le même schéma, avec le suffixe 26 sur le nom d'hôte : https://int-alfresco26.horsprod.ademe-scw.fr/, https://rec-alfresco26.horsprod.ademe-scw.fr/.

L'authentification est assurée par Keycloak.

Notions générales¶

Alfresco n'est pas une application monolithique : c'est un ensemble de composants qui se coordonnent autour d'un dépôt central. Comprendre ce découpage est nécessaire pour lire les values Helm, car chaque composant y correspond à une section.

Composant	Rôle	Hébergement
Repository (`alfresco-content-services`)	Le cœur : API REST, moteur de permissions, gestion des versions, cycle de vie des documents. Tout passe par lui.	Pod du cluster
Digital Workspace (`alfresco-adf-app`)	Interface utilisateur moderne, bâtie sur l'Alfresco Development Framework. Servie sous `/adw`. C'est le chart le plus adapté côté ADEME (voir Spécificités).	Pod du cluster
Share	Interface web historique, orientée sites collaboratifs. Servie sous `/share`. Déployée en parallèle du Digital Workspace, pas en remplacement.	Pod du cluster
Moteur de recherche	Index plein texte et par métadonnées, alimenté par le Repository. `alfresco` utilise Solr, `alfresco26` utilise Elasticsearch.	Pod du cluster
ActiveMQ	Bus de messages, utilisé pour les transformations et les événements.	Pod du cluster
Transform Service	Conversion de documents (PDF, aperçus, miniatures, OCR selon la configuration).	Pod du cluster
Base de données	Métadonnées, permissions, arborescence — pas le contenu des fichiers.	RDB Scaleway (PostgreSQL managé, hors cluster)
Contentstore	Les fichiers eux-mêmes.	PVC ReadWriteOnce monté sur le pod repository

Ce qu'il faut retenir de cette répartition¶

Les trois états d'Alfresco ne vivent pas au même endroit, et ne se sauvegardent donc pas de la même façon :

État	Où	Reconstructible ?
Métadonnées	RDB Scaleway	Non — sauvegarde via les snapshots RDB
Fichiers	PVC du pod repository	Non — sauvegarde au niveau du volume
Index de recherche	Solr / Elasticsearch	Oui, par réindexation depuis le Repository

Base et contentstore forment un couple indissociable

La base référence les fichiers du contentstore par leur chemin. Comme les deux sont sur des supports différents — RDB managée d'un côté, PVC Kubernetes de l'autre — rien ne garantit nativement que leurs sauvegardes soient cohérentes entre elles. Une restauration désynchronisée produit des documents introuvables ou orphelins.

Le PVC est ReadWriteOnce — le repository redémarre en Recreate

Un volume ReadWriteOnce ne peut être monté que par un seul pod à la fois. Le repository est donc déployé en stratégie Recreate : l'ancien pod est supprimé avant que le nouveau ne démarre. Il n'y a pas de recouvrement entre les deux versions, et donc pas de mise à jour sans interruption. C'est la contrainte structurante de tout ce qui suit — voir Déployer une nouvelle version.

Sur alfresco26, l'indexation Elasticsearch rejoue à chaque synchronisation

L'index Elasticsearch est reconstruit à chaque synchronisation du chart par ArgoCD. Une recherche incomplète juste après un déploiement n'est donc pas nécessairement un incident : l'index est peut-être encore en cours de reconstruction, pour une durée qui croît avec le volume documentaire.

Environnements¶

Quatre environnements, répartis sur deux clusters :

Environnement	Cluster	Namespace `alfresco`	Namespace `alfresco26`	Synchronisation ArgoCD
Intégration	horsprod	`int-alfresco`	`int-alfresco26`	automatique
Recette	horsprod	`rec-alfresco`	`rec-alfresco26`	automatique
Préproduction	horsprod	`preprod-alfresco`	—	automatique
Production	prod	`prod-alfresco`	—	manuelle

alfresco26 n'existe que sur intégration et recette. La préproduction et la production ne recevront pas de déploiement parallèle : elles seront montées en version sur place (voir La montée de version v26).

La production est en synchronisation manuelle — et ce n'est pas un oubli

La raison n'est pas la réindexation, mais le mode Recreate du repository : une synchronisation automatique supprimerait le pod en service avant d'avoir la garantie que la nouvelle image est disponible. Voir Pourquoi la production n'est pas en auto-sync.

Les deux déploiements¶

Il existe aujourd'hui deux déploiements Alfresco en parallèle sur intégration et recette. C'est un état transitoire.

	`alfresco`	`alfresco26`
Rôle	Déploiement courant, celui en service	Validation de la montée de version v26
Version Alfresco	7.2	26.1.0 (cible)
Moteur de recherche	Solr	Elasticsearch
PostgreSQL	13	17 (cible)
Environnements	int, rec, preprod, prod	int, rec
Statut	Pérenne	Temporaire
Chart	`argocd-ademe-appofapps/charts/alfresco`	`argocd-ademe-appofapps/charts/alfresco26`
Values infra	`argocd-ademe-appofapps/apps/alfresco/helm-values/environment.yaml`	`argocd-ademe-appofapps/apps/alfresco26/helm-values/environment.yaml`

alfresco26 a été créé pour préparer et valider la montée de version 26 sans toucher au déploiement en service. Une fois la v26 acquise, alfresco26 a vocation à être supprimé.

Conséquence pratique

Les deux déploiements ont leur propre chart et leurs propres values. Une modification apportée à alfresco26 n'est donc jamais répercutée automatiquement sur alfresco, et inversement. Toute configuration ajoutée à alfresco26 et destinée à servir sur les autres environnements doit être reportée explicitement.

La montée de version v26¶

Il n'y a pas de bascule

alfresco26 n'est pas un environnement cible vers lequel on basculerait le trafic ou les données. Sur intégration et recette, ce sont des duplications des environnements alfresco — créées précisément pour que les équipes puissent continuer à travailler sur alfresco pendant les travaux de migration. La montée de version y est ensuite jouée sur place, sur la copie.

La préproduction et la production, elles, ne seront pas dupliquées : elles seront montées en version directement dans leurs namespaces actuels (preprod-alfresco, prod-alfresco).

Ce que valident int-alfresco26 et rec-alfresco26

Ce sont des copies prises à un instant donné : le travail poursuivi sur int-alfresco et rec-alfresco ne s'y reporte pas. Elles valident le procédé de migration, pas l'état courant des données — et l'écart se creuse avec le temps.

Le passage de 7.2 à 26.1.0 n'est pas direct : il impose un palier intermédiaire pour la mise à niveau du schéma de base, et un changement de version de PostgreSQL. Les étapes, dans l'ordre :

Préparation — mise en place des nouveaux secrets nécessaires et des configurations.
Bascule de chart — passage au nouveau chart. C'est à ce moment que Solr laisse la place à Elasticsearch : il n'y a pas de migration de l'index à prévoir, celui-ci étant reconstruit et non transporté.
Palier 7.4.2.6 — le repository et son init container passent en 7.4.2.6. C'est cette étape qui met à niveau le schéma de la base de données.
Montée de PostgreSQL — la base passe de la version 13 à la version 17.
Cible 26.1.0 — passage en 26.1.0 sur l'ensemble des composants.

L'ordre n'est pas indicatif

Le palier 7.4.2.6 existe précisément parce que la migration du schéma doit se faire avant le reste, et l'init container en fait partie : le laisser sur une version antérieure au repository fait échouer la mise à niveau. De même, PostgreSQL est monté après la migration de schéma et avant le passage en 26.1.0.

La migration de schéma se fait sur place et ne se rejoue pas à l'envers

L'étape 3 modifie le schéma de la base en place. Une fois passée, la version précédente d'Alfresco ne sait plus lire cette base : il n'existe pas de chemin de retour par simple redéploiement de l'ancienne image. Sur préproduction et production, où la migration se fera directement dans le namespace en service, le retour arrière passe par une restauration de la base — la sauvegarde préalable est donc le seul filet.

État d'avancement¶

À ce jour, int-alfresco26 et rec-alfresco26 sont fonctionnels. La montée de version de la production est attendue pour le début de l'année 2027.

Les charts Helm¶

Localisation¶

Les deux charts vivent dans le dépôt argocd-ademe-appofapps, sous charts/ :

argocd-ademe-appofapps/
└── charts/
    ├── alfresco/          # déploiement courant — 7.2, Solr
    │   └── values.yaml    # values par défaut du chart
    └── alfresco26/        # validation v26 — Elasticsearch
        └── values.yaml

Ce sont deux charts indépendants, versionnés côte à côte. alfresco26 n'est pas une variante paramétrée d'alfresco : c'est une copie qui a divergé pour accueillir la v26 — le changement de moteur de recherche, à lui seul, rend les deux arborescences de values non interchangeables.

Spécificités¶

Ces charts ne sont pas les charts Alfresco officiels tels quels. Deux écarts principaux :

Un chart alfresco-adf-app forké — le chart d'origine ne permettait pas d'injecter des variables d'environnement depuis un secret. Il a donc été récupéré, modifié pour le permettre, puis tiré en dépendance directement depuis le dépôt où il est maintenu.
Ressources et secrets additionnels — un certain nombre de ressources Kubernetes et de secrets ont été ajoutés aux charts par rapport à l'amont.

Impact sur les mises à jour de chart

Ces adaptations sont portées dans nos charts, pas dans un overlay séparé. Reprendre une version amont d'un chart Alfresco implique donc de reporter ces modifications à la main : une resynchronisation naïve depuis l'amont les fait disparaître silencieusement.

(à compléter : liste précise des ressources et secrets ajoutés, et version amont de référence de chaque chart)

Les values et ArgoCD¶

Le déploiement n'est jamais appliqué à la main : chaque Application ArgoCD est déclarée en multi-source et assemble des values provenant de deux dépôts distincts.

Les trois sources, par priorité croissante¶

Priorité	Source	Emplacement	Rôle	Maintenue par
1 — la plus faible	Values par défaut du chart	`argocd-ademe-appofapps/charts/alfresco/values.yaml` `.../charts/alfresco26/values.yaml`	Socle du chart : valeurs de repli, structure des templates	Infra
2	Values de config infra	`argocd-ademe-appofapps/apps/alfresco/helm-values/environment.yaml` `.../apps/alfresco26/helm-values/environment.yaml`	Ce qui relève du cluster et de l'environnement	Infra
3 — la plus forte	Values de config app	`alfresco-cd/environment/base.yaml` `alfresco-cd/environment/config.yaml`	Ce qui relève de l'applicatif Alfresco	BlueXML

alfresco-cd a le dernier mot

En cas de clé définie à plusieurs niveaux, c'est la valeur d'alfresco-cd qui s'applique. Une modification apportée dans l'app-of-apps qui reste sans effet est le symptôme classique d'une clé déjà fixée côté alfresco-cd — dépôt dont BlueXML est propriétaire.

Ce que contient la source applicative¶

Le dépôt alfresco-cd sépare volontairement deux préoccupations dans deux fichiers :

Fichier	Contenu
`environment/base.yaml`	Images : dépôts d'images, tags, versions. C'est ici qu'on agit pour déployer une nouvelle version.
`environment/config.yaml`	Configuration Alfresco : properties et paramètres propres au produit.

L'équipe infra peut être sollicitée sur config.yaml

La répartition n'est pas étanche : BlueXML peut demander à l'équipe infra de modifier les configurations présentes dans alfresco-cd/environment/config.yaml. C'est le cas de figure où l'infra intervient dans le dépôt applicatif, sans que BlueXML cesse d'en être propriétaire.

Où modifier quoi

Le fichier à éditer se déduit de la nature du changement : une version se change dans base.yaml, une property Alfresco dans config.yaml, une valeur liée au cluster (ingress, ressources, stockage) dans l'environment.yaml de l'app-of-apps, et la structure même du chart dans le values.yaml du chart. Les deux premiers relèvent de BlueXML — l'équipe infra pouvant intervenir sur config.yaml à sa demande — les deux derniers de l'équipe infra.

Politique de synchronisation¶

Tous les environnements sont en synchronisation automatique, sauf la production, qui est en synchronisation manuelle.

Pourquoi la production n'est pas en auto-sync¶

L'enchaînement à comprendre :

Le contentstore est sur un PVC ReadWriteOnce, qu'un seul pod peut monter à la fois.
Le repository est donc en stratégie Recreate : l'ancien pod est supprimé avant que le nouveau ne soit démarré.
Si l'image de la nouvelle version n'a pas encore été rapatriée dans le registry Scaleway, le nouveau pod ne peut pas démarrer — et l'ancien n'existe déjà plus.

Le résultat est une indisponibilité du service, jusqu'à ce que l'image soit disponible. La synchronisation manuelle en production sert exactement à cela : ne déclencher la bascule qu'une fois la disponibilité de l'image vérifiée.

Retrouver une Application

Les Applications ArgoCD portent le même nom que le namespace qu'elles déploient : int-alfresco, rec-alfresco, preprod-alfresco, prod-alfresco, int-alfresco26, rec-alfresco26.

Déployer une nouvelle version¶

Les évolutions d'Alfresco sont livrées sous forme d'images : une montée de version se traduit donc par un changement de tag, pas par une modification de chart. La chaîne est automatisée, et la seule action manuelle — l'édition d'un tag dans alfresco-cd — est réalisée par BlueXML.

alfresco-cd — environment/base.yaml       ← modification des tags d'image (BlueXML)
    ↓ push
CI alfresco-cd
    ↓ recopie les images depuis les dépôts BlueXML
Registry Scaleway
    ↓
ArgoCD — synchronisation (automatique hors prod, manuelle en prod)
    ↓
Déploiement alfresco / alfresco26

Le déroulé¶

Modification des tags dans le base.yaml de l'environnement cible, sur le projet alfresco-cd, avec les versions d'images à déployer.
Push.
La CI récupère les images : elle rapatrie automatiquement les versions indiquées depuis les dépôts d'images BlueXML vers notre registry Scaleway.
ArgoCD synchronise : il récupère les nouvelles values et les applique aux déploiements — automatiquement hors production, sur déclenchement manuel en production.

Course entre la CI et ArgoCD : le risque n'est pas un pod cassé, c'est une coupure

Les étapes 3 et 4 sont enchaînées mais indépendantes : rien ne fait attendre ArgoCD que la CI ait fini. Si la synchronisation part la première, le repository — en Recreate — supprime le pod en service, puis le nouveau pod échoue à télécharger une image encore absente du registry Scaleway. Le service est alors coupé, pas simplement dégradé.

C'est pour cela que la production est en synchronisation manuelle : y vérifier la réussite du job CI avant de déclencher la synchronisation. Sur les environnements hors production, le risque est assumé — un ImagePullBackOff sur le repository après un déploiement s'y explique presque toujours par une CI non terminée ou en échec, avant de suspecter ArgoCD.

Exploitation¶

L'exploitation applicative relève de BlueXML. Côté infra, il n'existe pas aujourd'hui de point de contrôle applicatif dédié : la vérification se fait au niveau Kubernetes.

# adapter le namespace à l'environnement : int-, rec-, preprod-, prod-
kubectl -n int-alfresco get pods
kubectl -n int-alfresco logs deploy/alfresco-cs-repository -f

Retour arrière

Il n'existe pas de procédure de rollback formalisée, et il n'est pas prévu d'en établir une pour la montée en v26. Deux cas de figure :

Tant qu'aucune migration de schéma n'est intervenue — le retour au tag précédent dans base.yaml suffit.
Après une migration de schéma — la base n'est plus lisible par la version antérieure. Le retour arrière se fait alors par restauration de la base, décidée au cas par cas.

TODO¶

Lister précisément les ressources et secrets ajoutés aux charts, et la version amont de référence
Documenter la sauvegarde/restauration cohérente RDB + PVC contentstore
Documenter la montée de version sur place de preprod-alfresco et prod-alfresco, puis la suppression d'alfresco26