Skip to content

About

WordPress headless com Redis Streams, workers e MongoDB servindo frontends em PHP e Next.js.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

Complex WordPress — WordPress headless + fila + workers + frontends

Stack de desenvolvimento que usa o WordPress como CMS/painel e distribui o conteúdo para múltiplos frontends através de uma fila de eventos. O WordPress não fala direto com o banco de leitura: ele publica eventos de post (published / updated / trashed) num Redis Stream, e workers consomem esses eventos e gravam no MongoDB de cada cliente. Os frontends (PHP e Next.js) leem apenas do MongoDB.


Índice


Arquitetura

                          ┌──────────────────────────────────────────────────────────┐
                          │                       Traefik (proxy)                      │
                          │   wordpress.localhost · pma.· front.· next.  (HTTP→HTTPS)   │
                          └───┬───────────────┬───────────────┬───────────────┬────────┘
                              │               │               │               │
                       wp-admin/wp-json     phpMyAdmin     front (PHP)     next (Next.js)
                              │               │               │               │
                     ┌────────▼───────┐  ┌────▼────┐          │ lê           │ lê
                     │   WordPress    │  │ MySQL 8 │          │ Mongo        │ Mongo
                     │  (mu-plugin)   │  └─────────┘          │              │
                     └───────┬────────┘                      │              │
                             │ XADD (evento)                  │              │
                             ▼                                │              │
                     ┌───────────────┐                        │              │
                     │ Redis Stream  │   posts:events         │              │
                     └───────┬───────┘                        │              │
                             │ XREADGROUP (consumer group por cliente)        │
                             ▼                                 ▼              ▼
                     ┌───────────────┐                  ┌─────────────────────────┐
                     │  Worker(s)    │  ── upsert/del ─▶ │        MongoDB          │
                     │ (Node)        │                  │   coleção `posts`       │
                     └───────────────┘                  └─────────────────────────┘

Componentes:

  • WordPress é o painel onde o conteúdo é criado. Um mu-plugin observa as mudanças de status do post e publica eventos no Redis Stream. O WordPress só tem a extensão PHP redis — não conhece o MongoDB.
  • Redis Stream (posts:events) é a fila. Fila única, com o tipo do evento no campo action. Persistente, com replay e ack.
  • Worker (Node) consome o stream via consumer group e aplica upsert/delete na coleção posts do MongoDB. Cada cliente tem seu worker (e pode ter seu Mongo).
  • MongoDB guarda os posts no mesmo formato da REST API do WordPress com _embed (inclui autor, mídia destacada e termos embedados).
  • Frontends (PHP e Next.js) leem apenas do MongoDB.
  • Traefik roteia tudo por HTTPS (com redirect forçado de HTTP).

Fluxo de um post

  1. No painel do WordPress alguém publica / edita / manda pra lixeira um post.
  2. O hook transition_post_status dispara o mu-plugin mu-plugins/10-post-events.php, que:
    • monta o post no formato _embed da REST API (via rest_do_request interno);
    • faz XADD de um evento no stream posts:events com action = published | updated | trashed.
  3. O worker worker/index.js lê o evento (XREADGROUP):
    • published / updated → replaceOne(..., { upsert: true }) no Mongo;
    • trashed → deleteOne(...) no Mongo;
    • dá XACK. Se falhar, não dá ack e a mensagem é reprocessada depois (recuperação de pendências via XAUTOCLAIM).
  4. Os frontends leem a coleção posts do Mongo e renderizam.

O espelho no Mongo reflete somente posts publicados — exatamente o que a API listaria. Rascunho que nunca foi publicado não gera evento.


Serviços

Serviço Imagem / build Função Porta exposta
wordpress build ./wordpress CMS/painel; publica eventos no Redis (ext. redis) 8585 (host)
db mysql:8.0 Banco do WordPress interna
mongo mongo:7 Banco de leitura (posts no formato _embed) 27017
redis redis:7-alpine Fila de eventos (Redis Streams) + cache 6379
worker build ./worker Consome o stream e grava no Mongo (Node) interna
frontend build ./frontend Frontend PHP (ext. mongodb), lê do Mongo via Traefik
frontend-next build ./frontend-next Frontend Next.js (driver mongodb), lê do Mongo via Traefik
phpmyadmin phpmyadmin:latest Administração do MySQL via Traefik

Imagens customizadas:

  • wordpress — wordpress:latest + extensão PHP redis (phpredis).
  • frontend — php:8.3-apache + extensão PHP mongodb.
  • frontend-next — node:20-alpine, build standalone do Next.js (com HOSTNAME=0.0.0.0 para o Traefik alcançar o container em qualquer rede).
  • worker — node:20-alpine com ioredis + mongodb.

Modelo de eventos

Fila única (posts:events); o tipo vai no campo action. Isso preserva a ordem por post (published → updated → trashed), coisa que filas separadas por status perderiam.

action Quando Payload Ação do worker
published post passou a ter status publish post _embed upsert no Mongo
updated post já publicado foi atualizado post _embed upsert no Mongo
trashed post publicado foi para a lixeira — delete no Mongo

Campos da mensagem no stream: action, id, ts e (quando aplicável) payload (JSON do post no formato _embed).


Por que fila + workers?

  • Desacoplamento: o WordPress não precisa conhecer o banco de cada cliente. Ele publica uma vez; cada cliente consome no seu ritmo.
  • Fan-out: cada cliente é um consumer group próprio no mesmo stream → todos recebem todos os eventos, cada um com seu offset, com replay e ack.
  • Resiliência: se um worker cai, ao voltar ele retoma de onde parou; mensagens não ackadas são reivindicadas e reprocessadas (XAUTOCLAIM). (Pub/Sub perderia mensagens.)
  • Escala: enviar direto do WordPress para o banco de N clientes seria inviável; com a fila, basta subir mais workers.

URLs / hosts

Todos via HTTPS (certificado self-signed em .localhost; aceite o aviso do navegador). HTTP é redirecionado para HTTPS.

Host Serviço
https://wordpress.localhost/wp-admin/ Painel do WordPress
https://pma.wordpress.localhost/ phpMyAdmin
https://front.wordpress.localhost/ Frontend PHP (lê do Mongo)
https://next.wordpress.localhost/ Frontend Next.js (lê do Mongo)

Os hosts *.localhost resolvem para 127.0.0.1 na maioria dos sistemas. Se algum subdomínio não resolver, adicione-o ao /etc/hosts (ex.: 127.0.0.1 next.wordpress.localhost).

Primeiro acesso: instale o WordPress em https://wordpress.localhost/wp-admin/install.php.


Rotas do frontend Next.js

Padrão de permalink /%category%/%postname%/:

/                      → home (últimos posts)
/categorias            → índice de todas as categorias (com contagem)
/[category]            → arquivo da categoria (posts daquela categoria)
/[category]/[slug]     → post individual
  • A categoria sai dos termos embedados (_embedded["wp:term"]) do post no Mongo.
  • A página do post redireciona para a URL canônica se a categoria na URL não bater com a categoria real do post, e responde 404 para slug inexistente.

Pré-requisitos

  • Docker + Docker Compose.

  • Uma rede Docker externa chamada www, compartilhada com o Traefik:

    docker network create www
  • Um Traefik rodando e conectado à rede www, com entrypoints http e https. (A stack só declara os labels; o Traefik é externo.)


Como subir

# 1. configurar variáveis
cp .env.example .env      # e ajuste as senhas

# 2. build + subir tudo
docker compose up -d --build

# 3. instalar o WordPress
#    abra https://wordpress.localhost/wp-admin/install.php

# 4. publicar um post no painel e ver aparecer nos frontends

Comandos úteis

docker compose ps                      # status dos containers
docker compose logs -f worker          # acompanhar o worker
docker compose logs -f frontend-next   # acompanhar o Next.js
docker compose up -d --build <serviço> # rebuild de um serviço
docker compose down                    # parar e remover containers
docker compose down -v                 # idem + apagar volumes (apaga TODOS os dados)

Inspecionar a fila e o Mongo

# tamanho do stream e pendências do consumer group
docker compose exec redis redis-cli XLEN posts:events
docker compose exec redis redis-cli XPENDING posts:events client-default

# posts no Mongo
docker compose exec mongo mongosh --quiet wordpress \
  --eval 'db.posts.find({}, {"title.rendered":1, slug:1}).sort({date:-1}).toArray()'

Configuração (.env)

Variável Padrão Descrição
MYSQL_ROOT_PASSWORD — Senha root do MySQL
MYSQL_DATABASE wordpress Banco do WordPress
MYSQL_USER wordpress Usuário do MySQL
MYSQL_PASSWORD — Senha do usuário do MySQL
WORDPRESS_PORT 8585 Porta do WordPress publicada no host
MONGODB_DB wordpress Banco do MongoDB
MONGODB_COLLECTION posts Coleção dos posts
POSTS_STREAM posts:events Nome do Redis Stream de eventos
CLIENT_ID client-default Consumer group do worker (identidade do cliente)

Em produção, troque as senhas e considere habilitar autenticação no MongoDB (hoje está aberto na rede interna) e proteger a porta 27017/6379 expostas.


Escalar para vários clientes

Cada cliente é uma réplica do worker com um CLIENT_ID diferente (consumer group próprio). Assim todos recebem todos os eventos; se quiser bancos separados, aponte cada worker para outro MONGODB_URI/MONGODB_DB:

  worker-cliente-b:
    build: ./worker
    environment:
      CLIENT_ID: client-b            # consumer group próprio → recebe todos os eventos
      STREAM_KEY: posts:events
      MONGODB_URI: mongodb://mongo-cliente-b:27017
      MONGODB_DB: cliente_b
    networks:
      - wordpress_net

Estrutura de pastas

.
├── docker-compose.yml          # orquestração de toda a stack
├── .env / .env.example         # variáveis de ambiente
├── wordpress/
│   └── Dockerfile              # WP + extensão PHP redis
├── mu-plugins/                 # carregados automaticamente pelo WP (montados como volume)
│   ├── 00-example.php          # exemplo: campo reading_time na REST API
│   └── 10-post-events.php      # publica eventos (published/updated/trashed) no Redis
├── worker/
│   ├── Dockerfile
│   └── index.js                # consome o stream → upsert/delete no Mongo
├── frontend/                   # frontend PHP (lê do Mongo)
│   ├── Dockerfile              # php:8.3-apache + ext. mongodb
│   └── index.php
└── frontend-next/              # frontend Next.js (lê do Mongo)
    ├── Dockerfile              # build standalone, HOSTNAME=0.0.0.0
    ├── lib/
    │   ├── mongo.js            # conexão reaproveitada com o MongoDB
    │   └── posts.js            # helpers de categoria/caminho
    └── app/
        ├── page.js             # home
        ├── categorias/page.js  # índice de categorias
        └── [category]/
            ├── page.js         # arquivo da categoria
            └── [slug]/page.js  # post individual

Operação e troubleshooting

  • Posts antigos não aparecem no Mongo (backfill): o worker só processa eventos a partir da criação do consumer group. Posts publicados antes disso não foram enviados ao stream. Republicar: edite/atualize o post no painel, ou crie um comando que faça XADD dos posts já publicados.
  • Mensagem travada / erro repetido no worker: mensagens sem ack ficam pendentes e são reivindicadas via XAUTOCLAIM após ~30s. Veja XPENDING posts:events client-default.
  • 502 no frontend Next.js via Traefik: o build standalone precisa de HOSTNAME=0.0.0.0 (já configurado) para escutar em todas as redes; sem isso o Traefik, vindo da rede www, não alcança o container.
  • 404 em next.wordpress.localhost: confira a regra do router no docker-compose.yml (Host(...)) e se o container está na rede www.
  • Aviso de certificado: normal em .localhost (cert self-signed do Traefik).

About

WordPress headless com Redis Streams, workers e MongoDB servindo frontends em PHP e Next.js.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages