Configurar links contextuais e embed do Metabase na Central¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-06

O que é¶

O que você precisa configurar nos servidores para acender, no detalhe do app da Central:

Links contextuais (abrir GlitchTip / abrir Metabase) — funciona só com deploy, sem infra nova.
Embed do dashboard Metabase (iframe no painel) — exige um passo manual no Metabase (A0) + uma env.

O código dos dois lados (auth + authui) já está pronto e casado; falta configuração de servidor e deploy. Base técnica: decisão 0017.

Degradação graciosa: sem a env de embed, a Central mostra o link simples (abre o dashboard numa aba). Nada quebra — o embed apenas não aparece. Ou seja, dá pra deployar o auth antes de fazer o A0; o embed acende sozinho quando a env aparecer.

TL;DR (checklist)¶

[ ] 1. Conferir que GLITCHTIP_ADMIN_URL e METABASE_URL (recurso auth no Coolify) são as URLs públicas (as que o browser abre) — os links reusam essas.
[ ] 2. (embed) No Metabase: Admin → Settings → Embedding → habilitar Static embedding e copiar a Embedding secret key.
[ ] 3. (embed) No recurso auth (Coolify): setar METABASE_EMBEDDING_SECRET (secret) com essa key. Opcional: METABASE_EMBED_TTL_SECONDS (default 600).
[ ] 4. Deploy do auth (build novo) e do authui/central.
[ ] 5. (embed) Re-provisionar os apps que já existem (/xadm-setup, feature analytics) — o flag enable_embedding do dashboard só é setado no provision.
[ ] 6. Verificar (curl no catálogo + abrir o detalhe na Central).

1. Pré-requisito: URLs públicas (links contextuais)¶

Os links reusam as envs que os providers já usam para a API admin. Confirme que, no recurso auth (Coolify → auth → Environment), elas apontam para o host público (o que o navegador abre), não para uma URL interna de rede:

Env	Valor esperado	Usada para
`GLITCHTIP_ADMIN_URL`	`https://bug.xadm.biz`	link `bug.xadm.biz/<org>/<slug>`
`METABASE_URL`	`https://metabase.xadm.biz`	link `<metabase>/dashboard/<id>` e o embed

Se hoje elas já são as públicas (o GlitchTip/Metabase são acessados por esses hosts), não há nada a mudar aqui — os links contextuais funcionam já no deploy. Não precisa re-provisionar para o link (o org/slug do GlitchTip e o dashboard_id do Metabase já estão persistidos).

Se alguma dessas URLs for interna (rede docker/VPN) e diferente da pública, o link resolvido abriria um host que o browser não alcança. Nesse caso, me avise — aí trocamos por envs de URL pública dedicadas (glitchtip.public-url / metabase.public-url).

2. Habilitar Static embedding no Metabase (A0)¶

Só necessário para o embed (o link funciona sem isto). No Metabase (metabase.xadm.biz), logado como admin:

Admin settings → Embedding.
Ligar Static embedding (às vezes chamado "Embedding in other applications" / "Signed embedding"). Aceitar os termos.
Copiar a Embedding secret key (string longa; é o segredo que assina os JWT de embed).

Sem este passo, o Metabase recusa /embed/dashboard/<jwt> com 400 mesmo com a env setada.

3. Env de embed no recurso `auth` (Coolify)¶

No recurso auth (Coolify → auth → Environment Variables), adicionar:

Env	Valor	Secret?
`METABASE_EMBEDDING_SECRET`	a Embedding secret key do passo 2	sim ✅
`METABASE_EMBED_TTL_SECONDS`	validade da URL assinada em segundos (default `600` = 10 min)	não

Marque METABASE_EMBEDDING_SECRET como secret/build-time conforme o padrão da casa (injeção de secrets no Coolify). Salvar → redeploy do auth para as envs entrarem.

4. Deploy¶

auth — deploy do build novo (ver deploy no Coolify).
authui/central — deploy do build novo (o consumo dos links/embed é do lado da Central).

5. Re-provisionar os apps (só para o embed)¶

O MetabaseProvider seta enable_embedding:true no dashboard durante o provision. Dashboards provisionados antes desta versão não têm o flag — o embed não renderiza até ele existir.

Para cada app com analytics, rode o /xadm-setup (feature analytics) novamente — é idempotente: não recria nada, só garante o enable_embedding (um PUT no dashboard). Alternativa manual: no Metabase, abrir cada dashboard → Sharing → Embed → Static embedding → Publish.

Isto não é necessário para os links (item 1) — só para o embed.

6. Verificar¶

No contrato (rápido): com um token admin, olhar o links de um app:

curl -s https://auth.xadm.biz/api/admin/apps/<APP_ID> \
  -H "Authorization: Bearer <JWT_XADM_ADMIN>" | jq .links

Esperado (app com GlitchTip + Metabase ligada):

{
  "producao": "…", "docs": "…", "source": "…",
  "glitchtip": "https://bug.xadm.biz/<org>/<slug>",
  "metabase": "https://metabase.xadm.biz/dashboard/<id>",
  "metabase_embed": "https://metabase.xadm.biz/embed/dashboard/<jwt>#bordered=true&titled=true"
}

glitchtip/metabase presentes → links contextuais OK.
metabase_embed presente → embed OK (secret + enable_embedding no lugar). Se vier null mas os outros dois estão OK: falta a env (passo 3) ou o re-provision (passo 5) — a Central cai no link (esperado, não é erro).

Na Central (real): abrir o detalhe do app. Linha glitchtip/analytics mostra "abrir"; com embed + navegador web, o dashboard aparece embutido (iframe). Sem embed → o botão de link.

Reverter / desligar o embed¶

Remover METABASE_EMBEDDING_SECRET do recurso auth e redeploy → metabase_embed volta a null e a Central usa o link. Rotacionar o secret invalida as URLs em voo (TTL curto → impacto pequeno).

Resumo por servidor¶

Onde	O que fazer
Metabase (`metabase.xadm.biz`)	habilitar Static embedding, copiar a embedding secret key (passo 2)
Coolify → recurso `auth`	conferir `GLITCHTIP_ADMIN_URL`/`METABASE_URL` públicas (1); setar `METABASE_EMBEDDING_SECRET` (+`METABASE_EMBED_TTL_SECONDS`) (3); redeploy (4)
Coolify → recurso `authui`/central	deploy do build novo (4)
`/xadm-setup` (dev/CI)	re-provisionar analytics dos apps existentes p/ o `enable_embedding` (5)