Doze lições de produção a construir em Cockpit CMS v2

Lançámos quatro sites em produção com Cockpit CMS v2 nos últimos 18 meses. Incluindo este. Não é o headless CMS mais pesquisado no Google — essa coroa pertence ao Sanity, Strapi, Contentful, por alguma ordem — mas o Cockpit encaixa num nicho que os nomes famosos ignoram: workloads de conteúdo pequenas a médias em infraestrutura barata, editadas por pessoas que não querem uma sessão de formação de 90 minutos.

Eis doze coisas que aprendemos à força. Se estás a avaliar Cockpit, isto poupa-te uma semana.

1. Cockpit v2 não é Cockpit v1

Se um tutorial é anterior a 2024, deita fora. A forma da API mudou. O layout de diretorias mudou. O admin UI mudou. O data model mudou. v2 é, para efeitos práticos, um produto diferente. Filtra os resultados de pesquisa por "v2" ou "2024+".

2. Self-hosting significa que és o dono do WAL

O storage default do Cockpit v2 é SQLite. SQLite usa Write-Ahead Logging por defeito. Os ficheiros .sqlite-wal e .sqlite-shm interessam. Se fizeres rsync só do ficheiro .sqlite para um servidor novo, perdes writes recentes. Ou fazes checkpoint primeiro (PRAGMA wal_checkpoint(FULL)) ou copias os três ficheiros juntos.

3. O cache de schema é real

Depois de editar um model JSON, o Cockpit faz cache do schema parseado em storage/data/app.memory.sqlite. Até apagares esse ficheiro, o admin UI mostra campos antigos. Mete isto no teu deploy script.

4. i18n é por campo, não por documento

Marcas campos como i18n: true no schema. O Cockpit guarda como field (locale default) e field_pt, field_es, etc. A API serve o locale pedido via ?locale=pt. Planeia o schema com isto em mente; pôr i18n depois é trabalho manual de SQL.

5. A API key no URL é um tiro no pé

Não passes a API key como query parameter. Vai parar a logs, ao histórico do browser, a referrer headers. Usa o header HTTP api-key. Constrói o teu fetch helper para o forçar.

6. Assets de imagem precisam de proxy

A API de imagens do Cockpit exige a API key. Se referenciares URLs do Cockpit diretamente do frontend, expões a key. Escrevemos um proxy PHP de 30 linhas que aceita ?id=&w=, faz fetch com a key no servidor, e devolve WebP com headers de cache. Isto é verdade para qualquer headless CMS com asset API privada.

7. Self-HTTPS loopback parte em alguns hosts

Quando PHP em exemplo.com tenta chamar https://exemplo.com/cockpit/api/..., alguns shared hosts recusam o loopback. file_get_contents() devolve false sem erro. Solução: usa cURL (funciona onde file_get_contents não funciona) com fallback sensato. Não assumas que o teu ambiente local é igual ao de produção.

8. Cockpit não tem webhook nativo para "conteúdo mudou"

Há um event system dentro do PHP do Cockpit, mas não há webhook outbound out-of-the-box em save. Se precisas de invalidar um CDN no publish, escreves a ponte: um pequeno addon do Cockpit que ouve collection.save.after e faz POST para o endpoint de purge do CDN.

9. O JSON do model é a tua source of truth

O UI do Cockpit deixa-te construir models visualmente, mas mete os ficheiros JSON do model em version control. Guarda-os no repo ao lado do código do site. Se a tua instância do Cockpit morrer, podes reconstruir o schema todo a partir desses ficheiros. Os dados em si vivem em SQLite — faz backup à parte.

10. Roles e API keys estão desacoplados

Uma API key tem uma role anexa à criação. Mudar a role de uma API key no admin UI obriga a apagar a key e criar uma nova. Não pendures API keys num deploy antes de decidir que permissões precisa.

11. Markdown não é o default — WYSIWYG é

Se queres devs a escrever em Markdown e editores a escrever em WYSIWYG, escolhes o widget WYSIWYG. O output é HTML. Embebe Prism.js ou similar no lado de rendering se quiseres code blocks com syntax highlighting; o Cockpit não faz isso por ti.

12. A comunidade é pequena mas responsiva

As GitHub issues do Cockpit recebem atenção direta do maintainer (Artur Heinze). A documentação é irregular — lê o source. É o preço de admissão de um CMS sem VC por trás: menos Stack Overflow, mais ler modules/Content/Controller/Api.php quando algo se comporta de forma estranha. Achamos isto mais fiável do que lidar com paid support em fornecedores com VC.

Em resumo

Se precisas de um CMS que seja: gratuito, self-hostable em infra barata, rápido de editar, com i18n first-class e REST API a sério — o Cockpit é a melhor opção em 2025. Se precisas de edição colaborativa em tempo real, um exército de integrações out-of-the-box, ou documentação de mão dada — escolhe outro. O trade-off é honesto. Pagamo-lo com gosto.