Ga naar de inhoud

Een Blockstudio-site implementeren

Voor blokken volstaat het om een themamap naar een server te kopiëren: Blockstudio ontdekt ze op basis van het bestandssysteem en de caches merken zelf gewijzigde invoer op. Een echte site heeft meer onderdelen. Pagina’s op basis van bestanden bereiken de database pas wanneer je ze synchroniseert. Een statische prerender blijft de versie van gisteren van HTML tonen totdat iets deze vervangt. Een CDN die ervoor staat, blijft weergeven wat deze in de cache heeft opgeslagen.

Deze gids beschrijft de implementatie van een thema genaamd acme, waarin Blockstudio via Composer wordt gebundeld. De gids behandelt wat er in CI wordt uitgevoerd, wat er op de server gebeurt zodra de bestanden zijn geplaatst, hoe je het rapport over paginasynchronisatie leest en welke wp bs-opdrachten bij een release horen.

De release in één afbeelding

  1. Bouwen. CI installeert de productieafhankelijkheden Composer.
  2. Uploaden. Het thema, inclusief vendor/, wordt naar de server overgezet.
  3. Pagina’s synchroniseren. wp bs pages sync brengt de paginaberichten in overeenstemming met de bestanden en drukt een rapport af.
  4. De cache van de origin vernieuwen. Opgeslagen HTML wordt verwijderd wanneer pagina’s zijn gewijzigd en daarna opnieuw opgewarmd.
  5. De CDN leegmaken. Als laatste, zodat de edge de cache opnieuw vult vanaf een verse origin.

Voor stap 3 en 4 is WP-CLI op de server nodig. Het onderstaande script gebruikt ook jq om JSON te lezen.

Stap 1: Composer in CI

Bundel Blockstudio in het thema en commit composer.lock, zodat CI de exacte versie installeert die je hebt getest:

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

Installeer in CI zonder ontwikkelpakketten:

Shell
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

Blockstudio wordt vanuit de autoloader geïnitialiseerd en de eigen runtime-afhankelijkheden zijn gebundeld en voorzien van een namespace in het pakket. Wanneer het vanuit een vendor/-map wordt geladen, is de ingebouwde GitHub-updater uitgeschakeld, zodat Composer de enige manier blijft om de versie te wijzigen.

Stap 2: Bepaal wat schrijfbaar moet zijn

Blockstudio schrijft tijdens runtime gegenereerde bestanden. Weet waar dat gebeurt voordat een implementatie een map vervangt of vergrendelt:

  • Runtimecaches staan standaard onder wp-content/blockstudio/cache/. Wijs cache.path desgewenst toe aan een speciaal daarvoor bestemd schrijfbaar volume. Als je het pad wijzigt, begint de cache leeg.
  • Gecompileerde blokassets worden standaard geschreven naar een map _dist naast elk blok. Als je releasemap alleen-lezen is of bij elke implementatie wordt vervangen, stel dan assets.output in op cache, zodat ze in plaats daarvan onder de cachemap worden opgeslagen:
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

Je hoeft caches niet leeg te maken bij een implementatie. Elke cachevermelding is gekoppeld aan de invoerwaarden, waaronder blokbestanden, instellingen, het actieve thema en de plug-ins, en de versies van WordPress, PHP en Blockstudio. Een release waarin deze veranderen, krijgt dus nieuwe sleutels. In production en staging vertrouwt Blockstudio 20 seconden lang op een gevalideerde watch-snapshot voordat de bestanden opnieuw worden gecontroleerd. Daardoor kan het tot 20 seconden duren voordat een wijziging wordt opgemerkt. Het filter blockstudio/cache/watch_debounce wijzigt deze periode.

Stap 3: Pagina’s synchroniseren

Paginaberichten veranderen alleen via een expliciete synchronisatie. Frontend-, admin-, Ajax-, REST-, cron- en gewone WP-CLI-verzoeken ontdekken nooit paginabronnen en schrijven nooit paginaberichten. De implementatie moet dit dus expliciet aanvragen:

Shell
wp bs pages sync --format=json

Op een site waarvan het thema twee pagina’s heeft, about en contact, maakt de eerste uitvoering deze aan:

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": []
}

Zo lees je dit:

  • created, updated, unchanged, removed en failed geven het aantal pagina’s weer. Een pagina waarvan de bronvingerafdruk niet is veranderd, leidt niet tot schrijfopdrachten voor berichten of berichtmeta en activeert geen hooks voor updates.
  • Elke uitvoering vergelijkt de volledige pagina-inventaris. fullReconciliation geeft aan of de uitvoering als volledige synchronisatie geldt: true bij de eerste uitvoering, bij --full of wanneer de synchronisatie-engine zelf is veranderd, en false wanneer er een identiteit van een eerdere geslaagde synchronisatie bestaat. Andere tools kunnen dit gebruiken om te bepalen of alles opnieuw moet worden opgebouwd.
  • sourceIdentity is een deterministische vingerafdruk van de pagina-inventaris en de synchronisatie-engine. De opdracht slaat deze na een geslaagde uitvoering op.

Zonder --format=json drukt de opdracht één samenvattende rij en een succesregel af. In een CI-log, dat geen terminal is, worden de waarden in de rij gescheiden door tabs:

Text
discovered	created	updated	unchanged	removed	failed	source_id
2	0	1	1	0	0	7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.

Deze uitvoering volgde op een bewerking van about/index.php: één pagina is bijgewerkt en één is ongewijzigd gebleven.

Als synchronisatie mislukt

De opdracht eindigt met status 1 wanneer het ontdekken of synchroniseren een fout oplevert, waardoor de CI-stap mislukt. Het rapport JSON wordt nog steeds afgedrukt, dus sla het op in het log. Een ongeldige page.json ziet er zo uit:

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"
            }
        }
    ]
}

Beheerde pagina’s waarvan de bronnen zijn verdwenen, worden pas verwijderd nadat een uitvoering zonder fouten is voltooid. Zo verwijdert een release die niet kan synchroniseren geen actieve pagina’s. Verwijderde pagina’s gaan standaard naar de prullenbak; het filter blockstudio/pages/orphan_action kan trash, delete of keep retourneren.

Voer dit bij elke implementatie uit

Voer de synchronisatie ook uit als er geen pagina is veranderd. Als je implementeert in releasemappen en een symlink omschakelt, verwijst een ongewijzigde pagina nog steeds naar de template- en lay-outpaden van de vorige release totdat de volgende synchronisatie deze vernieuwt. Die vernieuwing wijzigt post_content of de wijzigingsdatum niet.

--authoritative en --full

Een gewone synchronisatie behoudt inhoud die redacteuren in blokken met een sleutel hebben gewijzigd. --authoritative vervangt beheerde inhoud door de inhoud uit de bestanden en kan een Page Sync-vergrendeling wissen. Gebruik dit wanneer de bestanden leidend moeten zijn: bijvoorbeeld bij het resetten van een staging-site of bij een site waar niemand pagina’s uit bestanden in de editor bewerkt. Gebruik dit niet bij elke implementatie van een site met actieve redacteuren.

--full markeert de uitvoering altijd als een volledige synchronisatie, ongeacht de opgeslagen identiteit. De vergelijking van pagina’s is bij elke uitvoering al volledig, dus de vlag wijzigt fullReconciliation in het rapport, niet welke pagina’s worden gecontroleerd. Geef de vlag mee als een latere stap op basis van die waarde alles opnieuw moet opbouwen.

Tools geschreven in PHP kunnen Blockstudio\Pages::reconcile() rechtstreeks aanroepen. De functie retourneert hetzelfde rapport, maar slaat de identiteit niet op: roep Blockstudio\Pages::store_successful_source_identity() aan zodra de rest van de release is gecontroleerd, bijvoorbeeld nadat een statisch artefact is geactiveerd.

Stap 4: De statische cache vernieuwen

Als de site statische prerendering gebruikt in de standaardmodus signature, maken paginaberichten die zijn bijgewerkt vanuit WP-CLI opgeslagen HTML niet zelf ongeldig. Lees het rapport en maak de cache leeg als er iets is veranderd. Warm de cache daarna op:

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}'

Elke uitvoering van wp bs prerender warm plaatst verouderde openbare URL’s in de wachtrij, rendert er maximaal warm.concurrency en drukt een samenvatting af. Tijdens deze uitvoering zijn vier van de zes URL’s in de wachtrij opgepakt en zijn alle vier niet gerenderd:

JSON
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}

Een URL die niet kan worden gerenderd, blijft verouderd en wordt opnieuw in de wachtrij geplaatst bij de volgende uitvoering. Daarom stopt de lus na de eerste uitvoering waarin niets wordt opgewarmd, in plaats van te wachten tot de wachtrij leeg is. Wat overblijft, wordt opgepakt door de geplande opwarmer of bij het volgende anonieme bezoek.

In de modus graph is de opwarmer per URL uitgeschakeld en plaatst warm niets in de wachtrij. Graph-sites vervangen stap 2 en 3 door hun eigen build, die de getroffen URL’s rendert en het resultaat atomair activeert. Zie signatuur- en graafmodi.

Stap 5: De CI-workflow

De onderstaande workflow is een voorbeeld voor GitHub Actions. De opzet is ook bruikbaar voor elk CI-systeem: bouwen, uploaden, het script op de server uitvoeren en de CDN leegmaken.

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 met cancel-in-progress: false plaatst een tweede push achter een lopende implementatie, in plaats van deze halverwege een synchronisatie te annuleren. PHP 8.2 is de minimumversie van Blockstudio. Vervang de laatste stap door de opdracht API voor het leegmaken van de cache van jouw CDN.

Onderhoudsopdrachten

Deze opdrachten horen niet bij elke release, maar moeten wel bekend zijn bij iedereen die het implementatiehandboek gebruikt.

De achterstand met verouderde vergrendelingen wegwerken. Releases van vóór 7.6.14 lieten bij elke inhoudswijziging een bestand .build.lock achter. Na de upgrade verwijdert WP-Cron deze bestanden in afgebakende batches. Zo controleer je de status en werk je de achterstand in één keer weg:

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 laat vergrendelingen die nieuwer zijn dan een uur of nog worden vastgehouden door een lopend verzoek staan tot de volgende uitvoering. Verwijder nooit handmatig vergrendelingsbestanden terwijl de site verkeer ontvangt.

De runtimecache leegmaken. wp bs cache clear maakt alles voor de huidige site ongeldig en wp bs cache clear --scope=runtime maakt één bereik ongeldig in alle namespaces. Het volgende verzoek bouwt de cache opnieuw op, dus voer dit uit wanneer er weinig verkeer is en alleen als daar reden voor is: invoerwijzigingen zorgen al voor nieuwe sleutels.

Blockstudio verwijderen. Een installatie als Composer heeft geen hook voor het deactiveren van plug-ins. Daarom worden cron-gebeurtenissen niet uit de planning verwijderd en wordt de drop-in voor vroeg serveren niet verwijderd wanneer het pakket verdwijnt. Voer dit uit voordat je de afhankelijkheid verwijdert:

Shell
wp bs teardown

Dit verwijdert de cron-gebeurtenissen en de status van statische prerendering die bij deze installatie horen, laat drop-ins en configuratiebestanden van andere partijen ongemoeid en zorgt ervoor dat een latere herinschakeling schoon kan beginnen.

Volgende stappen