Saltar al contenido

Implementar un sitio Blockstudio

Para los bloques, basta con copiar la carpeta del tema al servidor: Blockstudio los detecta en el sistema de archivos y sus cachés detectan los cambios en las entradas por sí solas. Un sitio real tiene más componentes. Las páginas basadas en archivos solo llegan a la base de datos cuando se sincronizan. Una renderización previa estática sigue sirviendo el HTML de ayer hasta que algo lo reemplaza. Un CDN delante sigue sirviendo lo que almacenó en caché.

Esta guía configura el despliegue de un tema llamado acme que incluye Blockstudio mediante Composer. Explica qué se ejecuta en CI, qué se ejecuta en el servidor después de copiar los archivos, cómo leer el informe de sincronización de páginas y qué comandos wp bs incluir en una versión.

La versión de un vistazo

  1. Compilar. CI instala las dependencias de producción Composer.
  2. Subir. El tema, incluido vendor/, llega al servidor.
  3. Sincronizar las páginas. wp bs pages sync pone las entradas de página al día con los archivos e imprime un informe.
  4. Actualizar la caché del origen. Se purga HTML almacenado si las páginas cambiaron, y luego se vuelve a calentar.
  5. Purgar CDN. Al final, para que el edge vuelva a cargar contenido desde un origen actualizado.

Los pasos 3 y 4 necesitan WP-CLI en el servidor. El script siguiente también usa jq para leer JSON.

Paso 1: Composer en CI

Incluye Blockstudio en el tema y confirma composer.lock para que CI instale la versión exacta que probaste:

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

En CI, instala sin los paquetes de desarrollo:

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

Blockstudio se inicia desde el autocargador y sus propias dependencias de ejecución están incluidas y con espacio de nombres dentro del paquete. Cuando se carga desde un directorio vendor/, su actualizador GitHub integrado se desactiva, de modo que Composer sigue siendo la única forma de cambiar la versión.

Paso 2: Decide qué debe poder escribirse

Blockstudio escribe archivos generados durante la ejecución. Averigua dónde antes de que un despliegue reemplace o bloquee un directorio:

  • Las cachés de ejecución están en wp-content/blockstudio/cache/ de forma predeterminada. Si lo prefieres, apunta cache.path a un volumen dedicado con permisos de escritura. Al cambiar la ruta, la caché empieza vacía.
  • Los recursos compilados de bloques se escriben por defecto en una carpeta _dist junto a cada bloque. Si el directorio de la versión es de solo lectura o se reemplaza en cada despliegue, establece assets.output en cache para guardarlos en el directorio de caché en su lugar:
JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "assets": {
    "output": "cache"
  }
}

No hace falta borrar las cachés durante el despliegue. Cada entrada de caché se identifica por sus entradas, incluidos los archivos de bloques, los ajustes, el tema y los plugins activos, y las versiones de WordPress, PHP y Blockstudio, así que una versión que los cambie tendrá claves nuevas. En production y staging, Blockstudio confía en una instantánea de vigilancia validada durante 20 segundos antes de volver a comprobar los archivos, por lo que puede tardar hasta 20 segundos en detectar un cambio. El filtro blockstudio/cache/watch_debounce modifica ese intervalo.

Paso 3: Sincronizar las páginas

Las entradas de página solo cambian mediante una sincronización explícita. Las solicitudes del frontend, del administrador, Ajax, REST, cron y las solicitudes normales de WP-CLI nunca descubren fuentes de páginas ni escriben entradas de página. El despliegue debe solicitarlo:

Shell
wp bs pages sync --format=json

En un sitio cuyo tema tiene dos páginas, about y contact, la primera ejecución las crea:

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

Cómo interpretarlo:

  • created, updated, unchanged, removed y failed cuentan las páginas. Si la huella de origen de una página no cambia, no se escriben entradas ni metadatos de entrada y no se activan hooks de actualización.
  • Cada ejecución compara el inventario completo de páginas. fullReconciliation indica si la ejecución cuenta como una sincronización completa: true en la primera ejecución, con --full o cuando cambia el propio motor de sincronización, y false cuando existe una identidad de una sincronización anterior correcta. Las herramientas posteriores pueden usarlo para decidir si deben reconstruirlo todo.
  • sourceIdentity es una huella determinista del inventario de páginas y del motor de sincronización. El comando la guarda tras una ejecución correcta.

Sin --format=json, el comando imprime una fila de resumen y una línea de éxito. En un registro de CI, que no es una terminal, la fila está separada por tabulaciones:

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

Esa ejecución se realizó después de editar about/index.php: una página se actualizó y otra no cambió.

Si falla la sincronización

El comando termina con el estado 1 si el descubrimiento o la sincronización indican un error, lo que hace fallar el paso de CI. Aun así, se imprime el informe JSON, así que guárdalo en el registro. Un page.json mal formado se ve así:

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

Las páginas gestionadas cuyas fuentes han desaparecido solo se eliminan después de que una ejecución termine sin errores, de modo que un lanzamiento cuyo proceso de sincronización falla no elimina páginas activas. Las páginas eliminadas van a la papelera de forma predeterminada; el filtro blockstudio/pages/orphan_action puede devolver trash, delete o keep.

Ejecútala en cada despliegue

Ejecuta la sincronización aunque no haya cambiado ninguna página. Si despliegas en directorios de versiones y cambias un enlace simbólico, una página sin cambios sigue apuntando a las rutas de plantilla y diseño de la versión anterior hasta que la siguiente sincronización las actualiza. Esa actualización no modifica post_content ni la fecha de modificación.

--authoritative y --full

Una sincronización normal conserva el contenido que los editores hayan modificado dentro de bloques con clave. --authoritative sustituye en cambio el contenido gestionado por el de los archivos y puede eliminar un bloqueo de Page Sync. Úsalo cuando los archivos deban prevalecer: al restablecer un sitio de pruebas o en uno donde nadie edite en el editor las páginas basadas en archivos. No lo incluyas en cada despliegue de un sitio con editores activos.

--full marca la ejecución como una sincronización completa independientemente de la identidad guardada. La comparación de páginas ya se completa en cada ejecución, por lo que la marca cambia fullReconciliation del informe, no qué páginas se comprueban. Pásala si un paso posterior usa ese valor para decidir si hace una reconstrucción completa.

Las herramientas escritas en PHP pueden llamar directamente a Blockstudio\Pages::reconcile(). Devuelve el mismo informe, pero no guarda la identidad: llama a Blockstudio\Pages::store_successful_source_identity() cuando hayas verificado el resto del lanzamiento, por ejemplo, un artefacto estático activado.

Paso 4: Actualizar la caché estática

Si el sitio usa prerenderizado estático en el modo signature predeterminado, las entradas de página actualizadas desde WP-CLI no purgan por sí solas la HTML almacenada. Lee el informe y purga si hubo cambios; después, calienta la caché:

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

Cada ejecución de wp bs prerender warm pone en cola las URL públicas obsoletas, renderiza hasta warm.concurrency de ellas e imprime un resumen. En esta ejecución, se reclamaron cuatro de las seis URL en cola y no se pudo renderizar ninguna de las cuatro:

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

Si una URL no se puede renderizar, sigue obsoleta y vuelve a ponerse en cola en la siguiente ejecución. Por eso el ciclo se detiene tras la primera ejecución que no calienta ninguna, en vez de esperar a que la cola quede vacía. El calentador programado o la siguiente visita anónima se encargarán de lo que quede.

En modo graph, el calentador por URL está desactivado y warm no pone nada en cola. Los sitios Graph sustituyen los pasos 2 y 3 por su propia compilación, que renderiza las URL afectadas y activa el resultado de forma atómica. Consulta los modos de firma y gráfico.

Paso 5: El flujo de trabajo de CI

El flujo de trabajo siguiente es un ejemplo de GitHub Actions. La misma estructura sirve para cualquier sistema de CI: compilar, subir, ejecutar el script en el servidor y purgar 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 con cancel-in-progress: false pone una segunda publicación en cola detrás de un lanzamiento en curso, en vez de cancelarlo a mitad de una sincronización. La versión 8.2 de PHP es la mínima de Blockstudio. Sustituye el último paso por la CDN de purga API.

Comandos de mantenimiento

No forman parte de cada lanzamiento, pero conviene incluirlos en la guía de despliegue.

Vaciar la cola de bloqueos heredados. Las versiones anteriores a 7.6.14 dejaban un archivo .build.lock por cada cambio de contenido. Después de actualizar, WP-Cron los elimina en lotes limitados. Para comprobarlos y vaciar toda la cola de una vez:

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 deja para la siguiente ejecución los bloqueos de hace menos de una hora o que sigan activos por una solicitud en curso. Nunca elimines archivos de bloqueo manualmente mientras el sitio esté atendiendo tráfico.

Borrar la caché de ejecución. wp bs cache clear purga todo para el sitio actual y wp bs cache clear --scope=runtime purga un ámbito en todos los espacios de nombres. La siguiente solicitud reconstruirá la caché desde cero, así que ejecútalo cuando haya poco tráfico y solo si tienes un motivo: los cambios en las entradas ya renuevan las claves.

Eliminar Blockstudio. Una instalación Composer no tiene un hook de desactivación de plugin, por lo que al desaparecer el paquete no se eliminan los eventos cron programados ni el complemento de atención temprana. Ejecuta esto antes de quitar la dependencia:

Shell
wp bs teardown

Elimina los eventos cron y el estado de prerenderizado estático que pertenece a esta instalación, deja intactos los complementos y archivos de configuración ajenos, y permite volver a activarla sin residuos.

Pasos siguientes