Pular para o conteúdo principal

Marca, temas e domínios-base

Este guia é para a equipe da plataforma (papel platform_admin, com segundo fator).

Nome da plataforma​

Em Administração › Marca (/admin/branding) fica o nome comercial, hoje Coda Cloud. Ele tem de 2 a 40 caracteres, sem marcação HTML. O wordmark e o remetente dos e-mails são derivados: cada espaço vira um ponto destacado ("Coda Cloud" → "Coda.Cloud"), e o remetente é "Equipe {nome}" em português e "{nome} Team" em inglês. A tela mostra a prévia nos dois idiomas, o histórico das alterações (quem, quando, de/para) e o estado da sincronização.

Depois de salvar, sem novo deploy:

  • o portal, o site público e os metadados de SEO mostram o nome novo em até 30 segundos;
  • os e-mails enviados a partir daí usam o nome novo no assunto, no corpo e no remetente;
  • o login e a conta do Keycloak e a status page são sincronizados pelo worker em até 1 minuto. A tela mostra Pendente, Sincronizado ou Erro para cada um; com erro, o worker tenta de novo a cada 5 minutos, e um alerta da plataforma avisa se o erro durar mais de 15 minutos;
  • esta documentação troca o nome no navegador assim que a página abre.

O nome comercial não muda identificadores internos: o realm e o tema atlas, os clients e cookies atlas-*, os namespaces e as imagens continuam com o codinome Atlas. A CLI, o SDK Go e o provider OpenTofu se chamam coda, independentemente do nome configurado.

A API equivalente é GET/PUT /api/v1/admin/branding (com If-Match) e GET /api/v1/admin/branding/history. O nome público fica em GET /api/v1/public/branding, sem login.

Temas da plataforma​

Em Administração › Marca › Temas (/admin/branding/themes) o Coda Cloud oferece um catálogo de oito temas visuais, todos com variante clara e escura e contraste de texto de pelo menos 4,5:1 verificado em cada publicação: Cósmico (padrão), Laranja e Água-marinha, Eclipse Púrpura, Vitamina C, Ardósia e Coral, Grafite e Âmbar, Violeta Elétrico e Pomar. O catálogo é versionado no repositório; o operador escolhe entre os publicados, sem editar cores.

A tela define três coisas, salvas juntas:

  • Tema da área logada: o padrão do portal, no console e em qualquer organização que não escolheu outro;
  • Tema do site: o site público, o login, o cadastro e a conta do Keycloak e esta documentação;
  • Temas habilitados para organizações: os que o Owner ou o Admin de uma organização pode escolher. O tema da área logada está sempre disponível, porque é para onde as organizações caem.

Antes de salvar, a tela mostra quantas organizações usam cada tema que você desmarcou e que passarão a ver o tema da área logada. A escolha delas não é apagada: se você habilitar o tema de novo, ela volta a valer. Cada tema tem prévia em claro e escuro. O modo claro ou escuro continua sendo escolha de cada usuário.

Os e-mails e a status page ficam sempre no tema padrão: os clientes de e-mail não suportam variáveis CSS e a status page precisa funcionar com a API fora do ar. O login, o cadastro e esta documentação aplicam o tema do site no navegador; se a API não responder, ficam com o tema padrão.

A API equivalente é GET/PUT /api/v1/admin/branding/themes (com If-Match e o corpo completo appThemeId, siteThemeId, enabledThemeIds). Os temas vigentes também vão em GET /api/v1/public/branding, em themes.app e themes.site.

Temas da organização​

Em Configurações › Aparência (/orgs/<organização>/settings/appearance), o Owner e o Admin escolhem o tema da organização entre os que a plataforma habilitou, com prévia em claro e escuro, ou marcam Seguir o tema da plataforma. Os demais membros veem o tema atual, sem editar. A escolha vale para todos os membros enquanto navegam na organização; fora dela, o portal usa o tema da área logada.

Escolher um tema exige o recurso branding.orgTheme do plano (Pro, Business e Enterprise na configuração padrão; o operador pode mudar por plano ou por organização em Administração › Planos). Sem o recurso, a escolha aparece bloqueada com o convite para mudar de plano, mas voltar a seguir a plataforma continua possível. Se o plano perder o recurso ou o operador desabilitar o tema escolhido, a organização passa a ver o tema da plataforma e a escolha fica guardada.

A API equivalente é GET/PUT /api/v1/orgs/{orgId}/theme.

Domínios-base​

Em Administração › Domínios-base (/admin/base-domains) ficam os domínios oferecidos aos projetos para o subdomínio gratuito (por exemplo, codacloud.app).

  1. Cadastro: informe o domínio registrável, em minúsculas, sem curinga nem porta. Ele entra em PENDING_SETUP. O cadastro é recusado se o domínio contiver os hosts da própria plataforma (portal, API, login, status, documentação ou domínio de aplicações), ficar sob eles, ou já for um domínio próprio verificado de um cliente.
  2. DNS: delegue a zona do domínio para o DNS da plataforma e publique o registro do checklist (*.<domínio-base> em CNAME para a borda). O checklist mostra o registro esperado e o valor encontrado na última verificação.
  3. Certificado curinga: a plataforma emite *.<domínio-base> (DNS-01) e cria o listener no gateway de tenants. Com DNS e certificado válidos, o domínio passa a READY. A verificação roda a cada hora e também por Verificar agora; um certificado com menos de 14 dias de validade gera alerta.
  4. Disponibilidade: só um domínio READY pode ser oferecido para novos subdomínios. Se ele não estiver na Public Suffix List, os cookies não ficam isolados entre clientes: confirme a inclusão ou aceite o risco com uma justificativa, que fica na auditoria.

Desativar bloqueia novos subdomínios; os existentes continuam servindo até serem liberados. A remoção é recusada enquanto houver subdomínio ativo ou em quarentena no domínio.