Roots Sage chez un infogéreur : la structure qu’imposent Kinsta ou WP Engine

composer.json déclare roots/acorn, vendor/ pèse quarante mégaoctets, et le thème attend un dossier storage/framework/views pour mettre en cache ses templates Blade compilés. Sur un poste de développement, tout cela se construit sans effort. Sur un hébergement infogéré, la même arborescence se heurte à des règles que l’hébergeur ne négocie pas.

Kinsta et WP Engine partagent une philosophie commune : le système de fichiers de production est en grande partie figé, les dépendances ne se compilent pas sur leurs serveurs, et le déploiement se fait par un dépôt Git plutôt que par un simple transfert de fichiers. Un thème Sage, pensé pour un cycle de développement moderne avec Acorn (le pont Laravel introduit à partir de la version 9 du framework), doit composer avec ces contraintes sans perdre ses fonctionnalités.

Ce que Sage attend d’un serveur

Depuis l’adoption d’Acorn, un thème Sage n’est plus un simple dossier de gabarits : c’est une mini-application qui a besoin d’écrire sur le disque à l’exécution. Trois zones sont concernées :

• storage/framework/views, où Blade dépose les templates compilés en PHP pur ;
• storage/logs, si le thème journalise des erreurs applicatives ;
• vendor/, qui doit exister avec toutes les dépendances Composer avant que WordPress ne charge le thème, faute de quoi functions.php échoue dès l’appel à require_once __DIR__ . '/vendor/autoload.php';.

En local, composer install puis npm run build suffisent. En production infogérée, ces deux commandes ne sont tout simplement pas disponibles au moment du déploiement.

Ce que Kinsta et WP Engine bloquent réellement

WP Engine expose un système de fichiers accessible en écriture uniquement sur wp-content/uploads et quelques répertoires temporaires ; le reste de l’arborescence, y compris le thème actif, est traité comme un artefact de déploiement immuable. Kinsta suit une logique proche avec son système de déploiement basé sur Git ou SFTP, où le contenu poussé devient la référence figée jusqu’au déploiement suivant.

Concrètement, cela signifie que storage/framework/views doit déjà exister, vide mais avec les bonnes permissions, dans l’artefact déployé. Si Acorn tente de créer ce dossier à la volée sur un système en lecture seule, la compilation Blade échoue silencieusement et WordPress affiche une page blanche, sans message exploitable dans les journaux applicatifs habituels.

Adapter le pipeline de build

La solution consiste à sortir la compilation du serveur de production et à ne pousser que le résultat. Un exemple de configuration pour une intégration continue simple :

#!/usr/bin/env bash
set -e
composer install --no-dev --optimize-autoloader
npm ci
npm run build
mkdir -p storage/framework/views storage/logs
chmod -R 775 storage
git add -f vendor public/build storage
git commit -m "build: assets compilés pour déploiement"
git push kinsta production

Le point délicat tient au .gitignore par défaut d’un projet Sage, qui exclut vendor/ et public/build : ces exclusions sont pensées pour un développement classique avec build côté serveur d’intégration, pas pour un déploiement figé chez un infogéreur. Il faut les lever spécifiquement sur la branche ou le dépôt utilisé pour le déploiement, sans les lever sur le dépôt de développement principal.

Le cas particulier du cache de configuration

Acorn propose une commande wp acorn config:cache qui fige la configuration Laravel dans un fichier unique pour accélérer le chargement. Cette commande doit être exécutée après le déploiement, pas avant, sinon elle capture des chemins de fichiers temporaires qui n’existeront plus une fois l’artefact copié sur les serveurs de production. Sur ces deux hébergeurs, cela implique un hook post-déploiement, généralement disponible via leurs interfaces respectives de webhooks.

Permissions et propriétaire des fichiers

Autre piège fréquent : les deux hébergeurs exécutent PHP-FPM sous un utilisateur dédié par site, distinct de celui qui reçoit le dépôt Git. Un dossier storage créé avec un propriétaire différent de celui du pool PHP-FPM reste inscriptible pour le déploiement mais pas pour le processus qui exécute réellement WordPress. Le symptôme est classique : le déploiement réussit, mais la première requête HTTP renvoie une erreur 500 avec, dans le journal PHP-FPM, une mention de type failed to open stream: Permission denied sur un chemin sous storage/framework.

La correction ne consiste pas à ouvrir les droits à 777, ce que refusent d’ailleurs souvent ces hébergeurs pour des raisons de sécurité, mais à s’assurer que le script de post-déploiement applique chmod et, si l’infrastructure le permet, chown avec l’utilisateur exact du pool PHP-FPM du site concerné.

Sur un projet Sage destiné à un infogéreur, le build appartient à l’intégration continue, jamais au serveur de production : c’est la règle qui évite neuf incidents sur dix.

Vérifier avant de livrer

Avant toute mise en production, une liste de contrôle courte évite l’essentiel des mauvaises surprises :

1. Le dossier vendor/ est bien présent dans l’artefact poussé, avec l’autoloader optimisé.
2. storage/framework/views et storage/logs existent et appartiennent au bon utilisateur.
3. Les assets compilés dans public/build correspondent à la version du thème réellement active.
4. La commande wp acorn view:clear est disponible pour vider le cache Blade en cas de déploiement raté, via WP-CLI si l’hébergeur y donne accès.

En résumé

Un thème Sage ne pose aucun problème particulier chez un infogéreur, à condition de traiter le serveur comme une cible de déploiement figée et jamais comme un environnement de build. Composer et npm restent en amont, les dossiers d’écriture sont préparés à l’avance, et les permissions suivent l’utilisateur réel du pool PHP-FPM plutôt qu’une convention générique. Le gain est net : un déploiement reproductible, sans compilation surprise en production, et un thème qui démarre du premier coup après chaque mise à jour.