Déployer un site Blockstudio
Pour les blocs, il suffit de copier le dossier du thème sur un serveur : Blockstudio les détecte dans le système de fichiers, et ses caches repèrent automatiquement les modifications. Un site réel comporte d’autres éléments. Les pages basées sur des fichiers n’atteignent la base de données qu’après leur synchronisation. Un pré-rendu statique continue de servir le HTML de la veille tant qu’il n’est pas remplacé. Un CDN placé devant le site continue de servir son contenu en cache.
Ce guide met en place un déploiement pour un thème nommé acme qui regroupe Blockstudio
avec Composer. Il décrit les opérations exécutées dans CI et sur le serveur après le transfert des fichiers,
la lecture du rapport de synchronisation des pages et les commandes wp bs à inclure dans une version.
Le déploiement en un schéma
- Build. CI installe les dépendances de production Composer.
- Upload. Le thème, y compris
vendor/, est transféré sur le serveur. - Réconcilier les pages.
wp bs pages syncaligne les pages avec les fichiers et affiche un rapport. - Actualiser le cache d’origine. Le contenu HTML stocké est purgé si des pages ont changé, puis préchauffé.
- Purger le CDN. En dernier, afin que le nœud périphérique se recharge depuis une origine à jour.
Les étapes 3 et 4 nécessitent WP-CLI sur le serveur. Le script ci-dessous utilise aussi jq pour lire JSON.
Étape 1 : Composer dans la CI
Intégrez Blockstudio au thème et validez composer.lock afin que la CI installe la version exacte que vous avez testée :
{
"require": {
"blockstudio/blockstudio": "^7.0"
}
}
<?php
require_once __DIR__ . '/vendor/autoload.php';
Dans la CI, installez sans les paquets de développement :
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
Blockstudio s’amorce à partir de l’autoloader, et ses propres dépendances d’exécution sont intégrées et placées sous espace de noms dans le paquet. Lorsqu’il est chargé depuis un répertoire vendor/, son outil de mise à jour GitHub intégré est désactivé ; Composer reste donc le seul moyen de changer de version.
Étape 2 : Déterminer ce qui doit être accessible en écriture
Blockstudio écrit des fichiers générés à l’exécution. Repérez leur emplacement avant qu’un déploiement ne remplace ou verrouille un répertoire :
- Les caches d’exécution se trouvent par défaut sous
wp-content/blockstudio/cache/. Vous pouvez définircache.pathsur un volume inscriptible dédié. Le changement de chemin repart d’un cache vide. - Les ressources de blocs compilées sont écrites par défaut dans un dossier
_distà côté de chaque bloc. Si votre répertoire de version est en lecture seule ou remplacé à chaque déploiement, définissezassets.outputsurcachepour les placer dans le répertoire de cache :
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"assets": {
"output": "cache"
}
}
Vous n’avez pas besoin de vider les caches lors d’un déploiement. Chaque entrée de cache dépend de ses données d’entrée, notamment des fichiers de blocs, des réglages, du thème et des extensions actifs, ainsi que des versions de WordPress, PHP et Blockstudio : une version qui les modifie obtient donc de nouvelles clés. En modes production et staging, Blockstudio fait confiance pendant 20 secondes à un instantané de surveillance validé avant de vérifier à nouveau les fichiers ; un changement peut donc mettre jusqu’à 20 secondes à être détecté. Le filtre blockstudio/cache/watch_debounce modifie cette durée.
Étape 3 : Réconcilier les pages
Les publications de page ne changent qu’à la suite d’une synchronisation explicite. Les requêtes du frontend, de l’administration, Ajax, REST, cron et les requêtes ordinaires WP-CLI ne recherchent jamais les sources de pages et ne modifient pas les publications de page. Le déploiement doit lancer cette opération :
wp bs pages sync --format=json
Sur un site dont le thème contient deux pages, about et contact, la première exécution les crée :
{
"discovered": 2,
"created": 2,
"updated": 0,
"unchanged": 0,
"removed": 0,
"failed": 0,
"fullReconciliation": true,
"sourceId": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd",
"sourceIdentity": {
"commit": "",
"dirtyHash": "",
"inventoryHash": "aaec5b9dd13d74eea872117b6167caa7a5d5c1abad9572fba22f6ddf6340adfe",
"engineFingerprint": "2c442442bb49f91e7187560e6db8f3475caa0b62b47708cab95b6ff13aba4469",
"hash": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd"
},
"pages": {
"about": {
"status": "created",
"postId": 545,
"locked": false
},
"contact": {
"status": "created",
"postId": 546,
"locked": false
}
},
"errors": []
}
Comment lire le résultat :
created,updated,unchanged,removedetfailedcomptent les pages. Si l’empreinte de la source d’une page n’a pas changé, aucune publication ni métadonnée de publication n’est écrite et aucun hook de mise à jour n’est déclenché.- Chaque passage compare l’inventaire complet des pages.
fullReconciliationindique si le passage compte comme une réconciliation complète :truelors de la première exécution, avec--fullou si le moteur de synchronisation lui-même a changé, etfalselorsqu’une identité issue d’une synchronisation précédente réussie existe. Les outils en aval peuvent s’en servir pour décider s’ils doivent tout reconstruire. sourceIdentityest une empreinte déterministe de l’inventaire des pages et du moteur de synchronisation. La commande l’enregistre après un passage réussi.
Sans --format=json, la commande affiche une ligne récapitulative et un message de réussite. Dans un journal de CI, qui n’est pas un terminal, la ligne est séparée par des tabulations :
discovered created updated unchanged removed failed source_id
2 0 1 1 0 0 7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.
Cette exécution a suivi une modification de about/index.php : une page a été mise à jour, l’autre est restée inchangée.
En cas d’échec de la synchronisation
La commande se termine avec le code 1 si la découverte ou la réconciliation signale une erreur, ce qui fait échouer l’étape de CI. Le rapport JSON est tout de même affiché ; consignez-le dans le journal. Voici à quoi ressemble un page.json mal formé :
{
"discovered": 0,
...
"failed": 1,
...
"pages": [],
"errors": [
{
"code": "invalid_page_json",
"message": "Invalid page.json file.",
"context": {
"path": ".../wp-content/themes/acme/pages/pricing/page.json"
}
}
]
}
Les pages gérées dont les sources ont disparu ne sont supprimées qu’après un passage sans erreur ; un échec de synchronisation lors d’une version ne supprime donc pas les pages actives. Les pages supprimées sont mises à la corbeille par défaut ; le filtre blockstudio/pages/orphan_action peut renvoyer trash, delete ou keep.
Exécuter à chaque déploiement
Lancez la synchronisation même si aucune page n’a changé. Si vous déployez dans des répertoires de version et changez de lien symbolique, une page inchangée pointe toujours vers les chemins de modèle et de mise en page de la version précédente jusqu’à ce que la prochaine synchronisation les actualise. Cette actualisation ne modifie ni post_content ni la date de modification.
--authoritative et --full
Une synchronisation normale préserve le contenu que les éditeurs ont modifié dans les blocs à clé. --authoritative remplace plutôt le contenu géré par celui des fichiers et peut supprimer un verrou Page Sync. Utilisez-le lorsque les fichiers doivent faire foi : pour réinitialiser un site de préproduction ou sur un site où personne ne modifie les pages provenant de fichiers dans l’éditeur. Ne l’ajoutez pas à chaque déploiement d’un site où des éditeurs travaillent activement.
--full indique que le passage est une réconciliation complète, quelle que soit l’identité enregistrée. La comparaison des pages est déjà complète à chaque passage ; l’option modifie donc fullReconciliation dans le rapport, et non les pages vérifiées. Transmettez-la si une étape ultérieure déclenche une reconstruction complète en fonction de cette valeur.
Les outils écrits en PHP peuvent appeler directement Blockstudio\Pages::reconcile(). Cette fonction renvoie le même rapport, mais n’enregistre pas l’identité : appelez Blockstudio\Pages::store_successful_source_identity() une fois le reste de la version vérifié, par exemple après l’activation d’un artefact statique.
Étape 4 : Actualiser le cache statique
Si le site utilise le prérendu statique static prerendering en mode signature par défaut, les publications mises à jour depuis WP-CLI ne purgent pas automatiquement le contenu stocké HTML. Lisez le rapport et purgez le cache si quelque chose a changé, puis préchauffez-le :
#!/usr/bin/env bash
set -euo pipefail
cd /var/www/example.com
report=$(mktemp)
# 1. Reconcile file-backed pages and keep the report.
if ! wp bs pages sync --format=json > "$report"; then
cat "$report"
exit 1
fi
jq '{discovered, created, updated, unchanged, removed}' "$report"
# 2. Drop stored HTML when page content changed.
changed=$(jq '.created + .updated + .removed' "$report")
if [ "$changed" -gt 0 ]; then
wp bs prerender purge
fi
# 3. Re-warm in bounded passes until a pass warms nothing.
for _ in $(seq 1 50); do
warmed=$(wp bs prerender warm | jq '.warmed')
[ "$warmed" -gt 0 ] || break
done
wp bs prerender status | jq '{files, queue}'
Chaque exécution de wp bs prerender warm met en file d’attente les URL publiques périmées, en traite jusqu’à warm.concurrency et affiche un récapitulatif. Lors de ce passage, quatre des six URL en file ont été prises en charge et les quatre ont échoué au rendu :
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}
Un URL dont le rendu échoue reste périmé et est remis en file d’attente à l’exécution suivante. C’est pourquoi la boucle s’arrête au premier passage qui ne préchauffe rien au lieu d’attendre que la file soit vide. Les éléments restants seront pris en charge par le préchauffeur planifié ou lors de la prochaine visite anonyme.
En mode graph, le préchauffeur par URL est désactivé et warm n’ajoute rien à la file d’attente. Les sites Graph remplacent les étapes 2 et 3 par leur propre processus de création, qui effectue le rendu des URL concernées et active le résultat de façon atomique. Consultez les modes signature et graph.
Étape 5 : Le workflow de CI
Le workflow ci-dessous est un exemple GitHub Actions. Le principe s’applique à n’importe quel système de CI : créer, transférer, exécuter le script sur le serveur, purger le CDN.
name: Deploy
on:
push:
branches: [main]
concurrency:
group: deploy-production
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: "8.2"
tools: composer:v2
- name: Install production dependencies
run: composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
- name: Configure SSH
run: |
mkdir -p ~/.ssh
echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519
ssh-keyscan example.com >> ~/.ssh/known_hosts
- name: Upload the theme
run: |
rsync -az --delete --exclude ".git" --exclude ".github" \
./ deploy@example.com:/var/www/example.com/wp-content/themes/acme/
- name: Sync pages and refresh the static cache
run: ssh deploy@example.com 'bash -s' < scripts/post-deploy.sh
- name: Purge the CDN
run: curl -fsS -X POST "${{ secrets.CDN_PURGE_URL }}"
concurrency avec cancel-in-progress: false met en attente un second déploiement derrière celui en cours au lieu de l’annuler au milieu d’une synchronisation. La version 8.2 de PHP est la version minimale de Blockstudio. Remplacez la dernière étape par la API de purge de votre CDN.
Commandes de maintenance
Ces commandes ne font pas partie de chaque version, mais le guide de déploiement doit les mentionner.
Vider la file d’attente des anciens verrous. Les versions antérieures à 7.6.14 laissaient un fichier .build.lock à chaque modification de contenu. Après la mise à niveau, WP-Cron les supprime par lots de taille limitée. Pour vérifier et vider toute la file d’attente :
wp bs cache status
wp bs cache cleanup
0 legacy build lock(s) across 0 cache namespace(s).
Next cleanup batch in 0 second(s).
cleanup conserve pour le prochain passage les verrous datant de moins d’une heure ou encore détenus par une requête en cours. Ne supprimez jamais les fichiers de verrouillage manuellement lorsque le site reçoit du trafic.
Vider le cache d’exécution. wp bs cache clear purge tout le contenu du site actuel et wp bs cache clear --scope=runtime purge une portée dans tous les espaces de noms. La prochaine requête repartira d’un cache vide ; lancez cette commande lorsque le trafic est faible et uniquement si vous avez une raison de le faire, car les changements d’entrée renouvellent déjà les clés.
Supprimer Blockstudio. Une installation Composer n’a pas de hook de désactivation d’extension ; aucun événement cron n’est donc déprogrammé et le drop-in de service anticipé n’est pas supprimé lorsque le paquet disparaît. Exécutez cette commande avant de supprimer la dépendance :
wp bs teardown
Cette commande supprime les événements cron et l’état de prérendu statique appartenant à cette installation, laisse intacts les drop-ins et les fichiers de configuration externes et permet une réactivation ultérieure dans un état propre.
Étapes suivantes
- Créer des pages à partir de fichiers : les pages réconciliées lors de ce déploiement.
- Référence des pages : le fonctionnement de la synchronisation, le PHP de réconciliation API et le contrat d’identité du déploiement.
- Référence de CLI : toutes les commandes
wp bs. - Mise en cache : emplacement du cache, identité, conservation et file d’attente des verrous.
- Servir WordPress comme HTML statique : le cache actualisé à l’étape 4.
- Composer : installations avec extension, extension must-use, thème et extension intégrée au thème.