Aller au contenu

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

  1. Build. CI installe les dépendances de production Composer.
  2. Upload. Le thème, y compris vendor/, est transféré sur le serveur.
  3. Réconcilier les pages. wp bs pages sync aligne les pages avec les fichiers et affiche un rapport.
  4. Actualiser le cache d’origine. Le contenu HTML stocké est purgé si des pages ont changé, puis préchauffé.
  5. 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 :

JSON
{
  "require": {
    "blockstudio/blockstudio": "^7.0"
  }
}
PHP
<?php
require_once __DIR__ . '/vendor/autoload.php';

Dans la CI, installez sans les paquets de développement :

Shell
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éfinir cache.path sur 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éfinissez assets.output sur cache pour les placer dans le répertoire de cache :
JSON
{
  "$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 :

Shell
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 :

JSON
{
    "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, removed et failed comptent 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. fullReconciliation indique si le passage compte comme une réconciliation complète : true lors de la première exécution, avec --full ou si le moteur de synchronisation lui-même a changé, et false lorsqu’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.
  • sourceIdentity est 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 :

Text
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é :

JSON
{
    "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 :

Shell
#!/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 :

JSON
{"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.

YAML
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 :

Shell
wp bs cache status
wp bs cache cleanup
Text
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 :

Shell
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