Doce lecciones de producción construyendo en Cockpit CMS v2

Hemos lanzado cuatro sitios en producción con Cockpit CMS v2 en los últimos 18 meses. Incluyendo este. No es el headless CMS más buscado en Google — esa corona pertenece a Sanity, Strapi, Contentful, en algún orden — pero Cockpit encaja en un nicho que los nombres famosos ignoran: workloads de contenido pequeñas a medianas en infraestructura barata, editadas por gente que no quiere una sesión de formación de 90 minutos.

Aquí van doce cosas que aprendimos a las malas. Si estás evaluando Cockpit, esto te ahorra una semana.

1. Cockpit v2 no es Cockpit v1

Si un tutorial es anterior a 2024, tíralo. La forma de la API cambió. El layout de directorios cambió. El admin UI cambió. El data model cambió. v2 es, a efectos prácticos, otro producto. Filtra los resultados de búsqueda por "v2" o "2024+".

2. Self-hosting significa que eres dueño del WAL

El storage default de Cockpit v2 es SQLite. SQLite usa Write-Ahead Logging por defecto. Los archivos .sqlite-wal y .sqlite-shm importan. Si haces rsync solo del archivo .sqlite a un servidor nuevo, pierdes writes recientes. O haces checkpoint primero (PRAGMA wal_checkpoint(FULL)) o copias los tres archivos juntos.

3. El caché de schema es real

Después de editar un model JSON, Cockpit cachea el schema parseado en storage/data/app.memory.sqlite. Hasta que borres ese archivo, el admin UI muestra campos viejos. Mételo en tu deploy script.

4. i18n es por campo, no por documento

Marcas campos como i18n: true en el schema. Cockpit los guarda como field (locale default) y field_pt, field_es, etc. La API sirve el locale pedido vía ?locale=pt. Planifica el schema con eso en mente; meterlo a posteriori es trabajo manual de SQL.

5. La API key en la URL es un tiro al pie

No pases la API key como query parameter. Acaba en logs, en historial de browser, en referrer headers. Usa el header HTTP api-key. Construye tu fetch helper para forzarlo.

6. Los assets de imagen necesitan proxy

La API de imágenes de Cockpit exige la API key. Si referencias URLs de Cockpit directo desde el frontend, expones la key. Escribimos un proxy PHP de 30 líneas que toma ?id=&w=, hace fetch con la key del lado servidor, y devuelve WebP con headers de cache. Esto vale para cualquier headless CMS con asset API privada.

7. Self-HTTPS loopback se rompe en algunos hosts

Cuando PHP en ejemplo.com intenta llamar a https://ejemplo.com/cockpit/api/..., algunos shared hosts rechazan el loopback. file_get_contents() devuelve false sin error. Solución: usa cURL (funciona donde file_get_contents no) con fallback sensato. No asumas que tu entorno local coincide con producción.

8. Cockpit no tiene webhook nativo para "contenido cambió"

Hay un event system dentro del PHP de Cockpit, pero no hay webhook outbound out-of-the-box al guardar. Si necesitas invalidar un CDN al publicar, escribes el puente: un addon pequeño de Cockpit que escucha collection.save.after y hace POST al endpoint de purge del CDN.

9. El JSON del model es tu source of truth

El UI de Cockpit te deja construir models visualmente, pero mete los archivos JSON del model en version control. Guárdalos en el repo junto al código del sitio. Si tu instancia de Cockpit muere, puedes reconstruir el schema entero desde esos archivos. Los datos en sí viven en SQLite — haz backup aparte.

10. Roles y API keys están desacoplados

Una API key tiene un role atado a la creación. Cambiar el role de una API key en el admin UI obliga a borrar la key y crear una nueva. No cuelgues API keys en un deploy antes de decidir qué permisos necesita.

11. Markdown no es el default — WYSIWYG es

Si quieres devs escribiendo en Markdown y editores escribiendo en WYSIWYG, eliges el widget WYSIWYG. El output es HTML. Embebe Prism.js o similar en el lado de rendering si quieres code blocks con syntax highlighting; Cockpit no hace eso por ti.

12. La comunidad es pequeña pero responsiva

Los GitHub issues de Cockpit reciben atención directa del maintainer (Artur Heinze). La documentación es irregular — lee el source. Es el precio de admisión de un CMS sin VC detrás: menos Stack Overflow, más leer modules/Content/Controller/Api.php cuando algo se comporta raro. Lo encontramos más fiable que lidiar con paid support de proveedores con VC.

En resumen

Si necesitas un CMS que sea: gratis, self-hostable en infra barata, rápido de editar, con i18n first-class y REST API en serio — Cockpit es la opción más fuerte en 2025. Si necesitas edición colaborativa en tiempo real, un ejército de integraciones out-of-the-box, o documentación de la mano — elige otro. El trade-off es honesto. Lo pagamos con gusto.