SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como alojar o Zitadel num VPS com Docker

Veja como alojar o Zitadel num VPS com Docker: a aplicacao usa cerca de 512 MB de RAM. Configure PostgreSQL, masterkey, TLS, SMTP, backups e upgrades.

O que é necessário para alojar o Zitadel num VPS

Para alojar o Zitadel num VPS, precisa de um host Docker, de um nome DNS público apontado para esse host, de PostgreSQL e de CPU e RAM suficientes para ambos. O guia de produção do Zitadel estima cerca de 512 MB de RAM e menos de um núcleo de CPU para a própria aplicação. A base de dados e o hashing de palavras-passe são os componentes que aumentam o consumo. O Zitadel é um fornecedor de identidade. Emite tokens através de OIDC (OpenID Connect) e SAML (security assertion markup language), para que os outros serviços deixem de manter as suas próprias listas de utilizadores. A instalação é um curl e um docker compose up. Os componentes que determinam se a instância se mantém operacional são a masterkey, o utilizador da base de dados, o SMTP (simple mail transfer protocol), a cópia de segurança e a primeira atualização.

Tudo o que se segue pressupõe Ubuntu 24.04, Docker Engine 24 ou posterior com o plugin Compose versão 2.24.4 ou posterior, e um nome como auth.example.com já a resolver para o servidor. Os overlays de TLS usam !override, que requer essa versão do Compose.

De quanta RAM de VPS o Zitadel precisa?

O guia de início rápido com Compose na documentação do Zitadel solicita 2 GB de RAM. Esse valor é apenas para o início rápido. O guia de produção do Zitadel publica números diferentes.

GráficoZitadel's own published sizing guidance, October 2026
Os dados por trás deste gráfico
[
  {
    "config": "Zitadel itself, under 1 core",
    "cpu_cores": 0.5,
    "ram_gb": 0.5
  },
  {
    "config": "HA node, reduced setup",
    "cpu_cores": 4,
    "ram_gb": 8
  },
  {
    "config": "HA node, logs and metrics on",
    "cpu_cores": 4,
    "ram_gb": 16
  }
]

Essas são recomendações publicadas, não medições de um servidor em execução. Considere-as como uma estimativa da carga de trabalho. O processo do Zitadel em si é leve: o guia indica cerca de 0.5 GB de RAM e afirma que pode rodar com menos de um núcleo de CPU. Os núcleos são necessários para o hashing de senhas, que é intencionalmente lento, portanto, um pico de logins gera um pico de uso de CPU; o guia recomenda manter 4 núcleos de CPU disponíveis para isso. O PostgreSQL representa a outra metade do custo: o mesmo guia estima cerca de um núcleo para cada 100 requisições por segundo e 4 GB de RAM por núcleo.

As duas linhas maiores não se referem a números para um servidor único. Para uma configuração mínima de alta disponibilidade, o guia recomenda um cluster de três nós, cada um com 4 núcleos e 16 GB, e afirma que é possível reduzir para cerca de 4 núcleos e 8 GB por nó se você excluir a coleta de logs e métricas. Não há dimensionamento especificado para um nó único.

Portanto, uma VPS de 2 GB iniciará esta stack, mas o valor está bem abaixo do que o guia estima apenas para o banco de dados quando o tráfego real chegar. O login é o serviço do qual todos os outros dependem. Quando ele está fora do ar, nenhum serviço que confia nele permite o acesso de usuários. Decidir que o orçamento de banco de dados e hashing do guia é maior do que você deseja gastar com autenticação é uma decisão razoável, e é muito mais barato tomar essa decisão agora do que após uma migração. A comparação entre Keycloak, Authentik e Zitadel aborda o custo de cada um em memória e trabalho operacional, e um servidor Authentik auto-hospedado é a resposta comum para servidores menores.

Obter a stack e fixar uma versão

mkdir zitadel-compose && cd zitadel-compose
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/.env.example
cp .env.example .env
chmod 600 .env

Esse ficheiro define quatro serviços que irá executar. O Traefik é o reverse proxy: encaminha por caminho e, com o overlay mais abaixo, termina o TLS (transport layer security). zitadel-api é o binário Go na porta 8080. zitadel-login é a interface de início de sessão disponibilizada em /ui/v2/login. postgres contém tudo. Uma cache Redis e um coletor OpenTelemetry estão no mesmo ficheiro, atrás de perfis do Compose, e permanecem desativados até serem ativados.

Ainda não execute docker compose up. O primeiro arranque cria a instância, e várias definições abaixo não podem ser alteradas depois sem trabalho adicional.

O .env que copiou fixa as suas próprias tags de imagem:

ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpine

A versão v4 atual é v4.20.3, lançada em 13 de novembro de 2026, quatro versões menores à frente da versão fixada no ficheiro fornecido. A versão anterior à v4.20.0, v4.19.5, de 15 de outubro de 2026, é a primeira abrangida pelo aviso técnico A-10018 do Zitadel: os endpoints de listagem afetados nas APIs v1 e v2 aplicam agora limites predefinidos e máximos. Assim, um cliente que faça uma listagem sem limite já não recebe todos os resultados e tem de usar paginação, e um pedido que solicite mais do que o máximo é rejeitado. Todas as versões posteriores, incluindo a v4.20.0, incluem essa alteração. Defina ZITADEL_VERSION para a versão que pretende executar e permaneça na linha v4, em vez de acompanhar sempre a versão mais recente. Ignore v4.18.0 se escolher manualmente uma versão: as notas dessa versão indicam que o passo de configuração falha nela e recomendam usar a v4.19.0. O curl acima obtém docker-compose.yml do branch main, que não está fixado a nenhum commit. Por isso, confirme cópias dos dois ficheiros num repositório git. Caso contrário, o mesmo comando executado numa máquina nova no próximo mês fornecerá um ficheiro diferente e não saberá o que mudou.

Substitua LOGIN_SESSION_COOKIE_SECRET em .env por um valor aleatório gerado por openssl rand -base64 32. A Login UI usa-o para assinar cookies de sessão, e as notas de lançamento da v4.19.5 alertam explicitamente para não manter o valor de exemplo.

Crie um utilizador dedicado e uma palavra-passe real para o Postgres

O .env fornecido liga o Zitadel ao PostgreSQL como superutilizador, com a palavra-passe postgres:

POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disable

Existe uma armadilha no passo de endurecimento aqui. A documentação do Zitadel indica para acrescentar POSTGRES_ZITADEL_PASSWORD ao .env, mas o docker-compose.yml base nunca lê essa variável, pelo que a sua definição não altera nada. Alterar o POSTGRES_ADMIN_PASSWORD isoladamente quebra a ligação, porque a palavra-passe também está escrita literalmente dentro da string DSN (data source name). O DSN é a linha que define como o Zitadel estabelece a ligação.

Os comentários no .env.example explicam o resto claramente: quando um DSN é configurado, o Zitadel utiliza esse utilizador diretamente e não cria um utilizador sem privilégios para si, pelo que a role tem de existir antes do primeiro arranque. Gere uma palavra-passe para a role, defina POSTGRES_ADMIN_PASSWORD com uma palavra-passe aleatória separada no .env antes de iniciar o Postgres, depois inicie o Postgres isoladamente e crie a role. A imagem do Postgres apenas aplica essa palavra-passe de administrador quando inicializa um diretório de dados vazio; alterar o .env mais tarde não altera a palavra-passe de uma base de dados existente.

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

docker compose --env-file .env -f docker-compose.yml up -d postgres

docker compose --env-file .env -f docker-compose.yml exec -T postgres \
  psql -U postgres -d postgres <<'SQL'
CREATE ROLE zitadel LOGIN PASSWORD 'the-password-you-generated';
ALTER DATABASE zitadel OWNER TO zitadel;
SQL

Essas chamadas psql são executadas dentro do contentor através do seu socket local, no qual a imagem oficial do Postgres confia, pelo que não solicitam uma palavra-passe. A propriedade é a parte que importa. A fase de inicialização do Zitadel cria os seus próprios esquemas (eventstore, projections, system) e tabelas. A propriedade da base de dados confere à role o privilégio CREATE necessário para inicializar esses esquemas. A alteração do PostgreSQL 15 nas permissões CREATE no esquema public é separada e não implica que a inicialização do esquema do Zitadel falhe.

Agora aponte o DSN para a nova role e mantenha a palavra-passe de administrador que definiu antes de iniciar o Postgres:

POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disable

O sslmode=disable deixa a ligação à base de dados sem encriptação na rede privada do Compose; a sua porta nunca é publicada no host. O guia de base de dados do Zitadel recomenda TLS para ligações de base de dados em produção. Após o primeiro arranque completo, verifique se a role é realmente proprietária dos seus dados:

docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'

Isso deverá listar um esquema eventstore, um esquema projections e um esquema system. Se esses esquemas não existirem, a fase de inicialização não chegou a esse ponto e o log do contentor da API indicará o motivo.

A masterkey e o custo de a perder

O Zitadel encripta segredos antes de os armazenar: credenciais de fornecedores de identidade, a palavra-passe SMTP, seeds de palavras-passe de utilização única (OTP) e chaves de máquina. A masterkey desbloqueia tudo isto. Ela tem exatamente 32 bytes e a documentação é direta quanto às consequências: não pode ser alterada sem perder o acesso aos dados encriptados.

Gere uma e substitua a linha de marcador de posição em .env:

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

Edite a linha ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters em vez de acrescentar uma segunda. O Compose utiliza a última definição de uma chave repetida, pelo que acrescentar funciona, mas um ficheiro que contenha duas linhas de masterkey é uma armadilha para quem o ler a seguir.

Agora, pense em onde essa chave reside. O ficheiro compose inicia o contentor da API da seguinte forma:

command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"

A masterkey fica, portanto, na linha de comandos do contentor, onde o docker inspect a mostra a qualquer pessoa que consiga aceder ao socket do Docker. Num VPS com um único administrador, este é um compromisso aceitável, e o modo em .env é o que a protege no disco. Se não for aceitável, monte a chave como um ficheiro e utilize --masterkeyFile /run/secrets/zitadel-masterkey em alternativa, o que mantém o valor fora dos argumentos do processo.

Copie a masterkey para o seu gestor de palavras-passe antes do primeiro arranque. Ela não aparece num dump da base de dados, pelo que um dump restaurado com uma masterkey diferente produz uma instância que não consegue ler os seus próprios segredos. Guarde-a num local diferente do arquivo que contém o dump, para que um backup roubado não contenha simultaneamente os dados encriptados e a chave para os mesmos.

Defina o domínio externo antes do primeiro arranque

ZITADEL_DOMAIN em .env alimenta ZITADEL_EXTERNALDOMAIN no contentor, e é o nome que os seus utilizadores escrevem. O Zitadel deriva o emissor OIDC, o URI base da interface de login, os endpoints SAML e o nome de login do primeiro administrador a partir dele, portanto não é algo meramente cosmético.

ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=true

O Zitadel resolve a instância com a qual está a comunicar a partir do cabeçalho Host. Se esse cabeçalho não corresponder a um domínio conhecido, todos os pedidos recebem a mesma resposta:

ID=QUERY-1kIjX Message=Instance not found

Verifique dois pontos quando encontrar esse erro. Ou ZITADEL_DOMAIN não é o nome que está a utilizar para navegar, ou um proxy à frente está a reescrever Host para o endereço upstream. Navegar para o endereço IP do servidor em vez do nome também produz este erro.

Pode alterar estes valores mais tarde. O Zitadel tem de executar novamente a sua fase de configuração para aplicar a alteração, e todas as aplicações que já registou mantêm os seus URIs de redirecionamento antigos. Escolher o nome final agora é muito menos dispendioso do que migrá-lo posteriormente.

Terminar TLS com a camada Let's Encrypt

Para um domínio público, adicione a camada Let's Encrypt do Zitadel. Ela altera o Traefik para o desafio HTTP ACME (automatic certificate management environment) e substitui as portas publicadas por 80 e 443, portanto, nenhum outro serviço na máquina pode utilizar estas portas.

curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .env

A camada também define ZITADEL_EXTERNALPORT: 443 e ZITADEL_EXTERNALSECURE: true no contentor da API, o que garante que o URL público e os URLs que o Zitadel gera para si próprio coincidam. O registo A deve resolver antes de iniciar, pois o desafio HTTP falha sem ele.

Se já termina TLS no nginx ou num balanceador de carga, utilize docker-compose.mode-external-tls.yml em vez disso e defina TRAEFIK_TRUSTED_IPS para os intervalos a partir dos quais o seu proxy envia tráfego. O Traefik apenas aceita cabeçalhos X-Forwarded-* de endereços nessa lista. A camada define explicitamente o URL externo e os URLs de login do Zitadel para HTTPS.

Um proxy a montante tem duas funções que o Zitadel exige rigorosamente. Deve utilizar HTTP/2 para o backend, porque a API é gRPC. E deve passar o Host inalterado, juntamente com o X-Forwarded-Proto: https. Com este stack Compose, a configuração do nginx tem este formato:

server {
    listen 443 ssl;
    http2 on;
    ssl_certificate     /etc/certs/selfsigned.crt;
    ssl_certificate_key /etc/certs/selfsigned.key;
    location /ui/v2/login {
        proxy_pass http://YOUR_LOGIN_UPSTREAM:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        grpc_pass grpc://YOUR_API_UPSTREAM:8080;
        grpc_set_header Host $host;
        grpc_set_header X-Forwarded-Proto https;
    }
}

Substitua os marcadores de posição a montante por endereços que o nginx consiga alcançar. Se servir o Zitadel numa porta diferente da 443, utilize grpc_set_header Host $host:$server_port; para que a porta seja incluída no cabeçalho. O resto é um host virtual comum, e uma configuração de reverse proxy nginx lida linha a linha cobre as partes que não são específicas do Zitadel.

O primeiro administrador e a alteração obrigatória da palavra-passe

O primeiro arranque cria uma instância, uma organização e um administrador humano. O nome de início de sessão é zitadel-admin@ mais zitadel. mais o seu domínio externo. Com ZITADEL_DOMAIN=auth.example.com, fica assim:

zitadel-admin@zitadel.auth.example.com

A palavra-passe é Password1!, exceto se definir uma própria. O padrão original do Zitadel obriga a alterá-la no primeiro início de sessão, mas o ficheiro Compose fornecido substitui esse comportamento:

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

Essa linha está definida diretamente em docker-compose.yml, em vez de ser lida de .env. Por isso, coloque os seus valores num pequeno overlay próprio. Dê-lhe o nome docker-compose.local.yml:

services:
  zitadel-api:
    environment:
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS: you@example.com
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: "a-long-temporary-password"
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "true"

O Compose só carrega docker-compose.override.yml automaticamente quando é executado sem a opção -f. Todos os comandos do guia do Zitadel passam -f, o que desativa esse comportamento. Em vez de repetir uma lista crescente de opções, fixe a lista de ficheiros em .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.yml

Agora inicie-o:

docker compose pull
docker compose up -d --wait

--wait mantém o comando em execução até os healthchecks passarem. Quando o contentor da API nunca chega a esse estado, o Compose termina com dependency failed to start: container zitadel-zitadel-api-1 is unhealthy, e docker compose logs zitadel-api contém o motivo. O contentor recebe um nome baseado no projeto. O ficheiro Compose fornecido define esse nome através de um name: zitadel de nível superior, por isso o nome do diretório não aparece. Num primeiro arranque, o motivo costuma ser o comprimento da masterkey ou o DSN da base de dados.

Inicie sessão em https://auth.example.com/ui/console, altere a palavra-passe e ative um segundo fator para essa conta antes de criar qualquer outra coisa. Cada valor ZITADEL_FIRSTINSTANCE_* só se aplica enquanto a primeira instância está a ser criada. Depois de a instância existir, alterá-los não produz qualquer efeito.

Por que a redefinição de senha não funciona enquanto o SMTP não estiver operacional

Um provedor de identidade que não consegue enviar e-mails está com uma falha que pode permanecer oculta por semanas. O Zitadel envia e-mails para convites de utilizadores, verificação de endereços, links de redefinição de senha, códigos de uso único e avisos de reivindicação de domínio. Sem um provedor SMTP configurado, o Console ainda reporta a ação como concluída, e a mensagem vai para o processamento de notificações sem ter para onde ser enviada. Na v4.20.0, as notificações usam o modo legado por padrão (LegacyEnabled: true), que ignora as configurações MaxAttempts: 3 e MaxTtl: 5m do worker paralelo. Esses valores não descrevem o comportamento padrão de retentativa de notificações. Nada avisa a pessoa que aguarda pelo link.

Configure-o no Console, nas definições da instância em https://auth.example.com/ui/console/settings. O formulário do provedor SMTP solicita um endereço de e-mail do remetente, um nome de remetente, o host e a porta, um utilizador, uma senha SMTP e um seletor para TLS. Use o botão de teste no formulário antes de guardar, pois ele envia uma mensagem real: ou ela chega ou não chega. Ative o provedor para que o Zitadel o utilize para enviar e-mails.

Existe um conjunto correspondente de variáveis de ambiente, ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST e as suas variantes. Elas aplicam-se quando uma instância é criada. Numa stack que já está em execução, elas não têm efeito, portanto o Console é o local correto para uma instância existente.

Dois pontos sobre o envio a partir de uma VPS, pois é aqui que geralmente ocorre a falha. Verifique a política de SMTP de saída do seu provedor antes de escolher um relay: a DigitalOcean bloqueia as portas 25, 465 e 587 nos Droplets por padrão, portanto a porta 587 não é uma solução universal. Use um relay autenticado numa porta que o seu provedor permita. E publique registos SPF (sender policy framework) e DKIM (domainkeys identified mail) para o domínio de envio, caso contrário o link de redefinição cairá no spam, o que para o utilizador parece exatamente como se o e-mail nunca tivesse sido enviado.

Na v4.20.0, as ligações SMTP TLS de saída rejeitam cadeias de certificados através das CAs intermediárias comprometidas da eMudhra. Um relay afetado precisa de um certificado de substituição.

Faça o teste antes de convidar qualquer pessoa. Crie um utilizador descartável, solicite uma redefinição de senha e verifique se a mensagem chega. Se não chegar, docker compose logs -f zitadel-api indica a falha de SMTP. A senha SMTP é armazenada encriptada na base de dados, o que é mais uma das coisas que a masterkey protege para si.

Faça backup do Postgres e da masterkey separadamente

Tudo o que o Zitadel conhece está no PostgreSQL. A masterkey é o que permite desencriptar esses dados. Faça o backup em dois locais diferentes.

Primeiro, crie o dump:

sudo install -d -m 700 /srv/zitadel-backups
docker compose exec -T postgres \
  pg_dump -U postgres -Fc zitadel > "/srv/zitadel-backups/zitadel-$(date +%F).dump"

-Fc é o formato personalizado. Ele comprime os dados durante a exportação, e o pg_restore consegue ler partes específicas desse formato. exec -T remove a necessidade de um terminal, o que é importante porque este comando é executado pelo cron sem um terminal associado.

Depois, envie esse diretório para um local externo com o restic, que cifra e elimina duplicados:

export RESTIC_REPOSITORY="sftp:backup@backup.example.com:/srv/restic/zitadel"
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init
restic backup /srv/zitadel-backups
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

restic init é executado uma única vez, apenas no primeiro dia. Coloque o dump e os dois últimos comandos em /usr/local/bin/zitadel-backup.sh e execute-o todas as noites:

0 3 * * * /usr/local/bin/zitadel-backup.sh

Faça backup do .env e de todos os ficheiros Compose que utiliza num repositório git. A masterkey é a exceção a tudo isto. Guarde-a no seu gestor de palavras-passe e num segundo local que não seja este repositório restic, porque um arquivo que contenha a base de dados e a respetiva chave de desencriptação deixa de ser um backup de um sistema cifrado.

Um backup que nunca foi restaurado é apenas uma suposição. Restaure-o numa base de dados temporária no mesmo servidor e verifique o conteúdo:

docker compose exec -T postgres createdb -U postgres zitadel_restore_test
docker compose exec -T postgres pg_restore -U postgres -d zitadel_restore_test \
  < /srv/zitadel-backups/zitadel-2026-08-21.dump
docker compose exec -T postgres psql -U postgres -d zitadel_restore_test -c '\dt eventstore.*'
docker compose exec -T postgres dropdb -U postgres zitadel_restore_test

Uma lista de tabelas no esquema eventstore significa que o dump é válido. Uma mensagem de erro a indicar que o esquema não existe significa que o dump não é válido. Assim, descobrirá o problema num dia em que a falha não lhe custa nada. O padrão geral para fazer backup e atualizar uma stack Compose aplica-se aqui quase sem alterações. Manter a masterkey fora do mesmo arquivo é a única parte específica do Zitadel.

Atualizar o Zitadel sem perder a instância

Uma atualização consiste em alterar a versão em .env e executar dois comandos:

docker compose pull
docker compose up -d --wait

Compreenda o que o segundo comando faz antes de o executar numa instância onde as pessoas iniciam sessão. O comando do contentor é start-from-init. Ele executa as fases de init e setup antes de começar a servir pedidos, e a fase de setup corresponde às migrações da base de dados. Portanto, uma alteração de versão executa migrações do esquema na base de dados em produção quando o contentor arranca, sem intervenção, enquanto --wait fica à espera de um healthcheck. É precisamente por isso que o teste de restauro acima não é opcional.

Faça um dump novo imediatamente antes da atualização. O dump da noite anterior é diferente.

Na v4.20.3, os inícios de sessão em curso através de fornecedores de identidade externos têm de ser reiniciados, e os códigos de autorização Login V1 ainda não utilizados são rejeitados uma vez. As interfaces de início de sessão personalizadas precisam da permissão session.link para concluir pedidos OIDC ou SAML. Conceda essa função ao respetivo utilizador de serviço com IAM_LOGIN_CLIENT antes da atualização. O utilizador de serviço fornecido para o Login V2 já tem essa função. As verificações de palavras-passe da Session API aplicam agora a política de início de sessão da organização do utilizador. Por isso, as organizações que desativem o início de sessão com nome de utilizador e palavra-passe têm de encaminhar os utilizadores para o seu fornecedor de identidade.

Não salte uma versão principal. Antes de passar da v3 para a v4, atualize primeiro para a v3.4.1 ou posterior. A v4 torna obrigatórias as chaves web OIDC e remove o método de assinatura legado. Assim, se a instância v3 nunca tiver ativado chaves web, os tokens assinados com as chaves legadas deixam de poder ser verificados depois da atualização. O aviso técnico A-10017 do Zitadel indica que os tokens de acesso JWT e os ID tokens existentes podem tornar-se inválidos imediatamente e que os utilizadores podem ter de iniciar sessão novamente. A correção consiste em passar primeiro pela v3.4.1 ou posterior e deixar expirar os tokens e as sessões assinados com o método legado antes da atualização, ou aceitar uma janela planeada para novo início de sessão. Se já executar a v3.4.1 ou posterior e tiver aguardado desde a ativação das chaves web, o aviso indica que não é necessária qualquer ação.

Monitorize a fase de setup com docker compose logs -f zitadel-api. As migrações num eventstore grande podem demorar vários minutos, e o Traefik não encaminhará pedidos para a API até o healthcheck passar. Por isso, o site ficará indisponível durante esse período. Planeie essa indisponibilidade em vez de a descobrir durante a atualização.

O rollback não consiste em voltar a colocar a tag antiga. Depois de as migrações serem executadas, o binário antigo não compreende o esquema que encontra. Assim, fazer rollback significa restaurar o dump. Depois de a instância ter utilizadores reais, passe para docker-compose.prodlike.yml, o overlay que executa init e setup como passos separados do arranque. Dessa forma, uma migração é algo que ativa e monitoriza, em vez de ser um efeito secundário do reinício de um contentor.

O que apontar para o novo provedor de identidade

No Console, crie um projeto e, em seguida, uma aplicação dentro dele. Escolha OIDC para qualquer aplicação moderna. O Zitadel fornece um ID de cliente, um segredo de cliente e um documento de descoberta em https://auth.example.com/.well-known/openid-configuration. A maioria dos softwares self-hosted compatíveis com início de sessão único requer exatamente estes dados.

Muitos softwares não são compatíveis com esta funcionalidade ou só a disponibilizam num plano pago. No primeiro caso, o oauth2-proxy à frente da aplicação transforma qualquer serviço HTTP em algo que o Zitadel pode proteger. No segundo caso, vale a pena ler o custo do SSO nas aplicações self-hosted antes de planear uma migração com base numa funcionalidade que ainda não adquiriu.

FAQ

Quanta RAM e CPU o Zitadel autohospedado necessita?

O guia de produção do Zitadel indica que o próprio Zitadel necessita de cerca de 0.5 GB de RAM e pode correr com menos de um núcleo de CPU, recomendando-se a reserva de 4 núcleos para o hashing de palavras-passe. O PostgreSQL é orçamentado separadamente, aproximadamente um núcleo por cada 100 pedidos por segundo e 4 GB de RAM por núcleo. Os valores mais elevados no guia referem-se a cada nó num cluster de alta disponibilidade de três nós: 4 núcleos e 16 GB cada, ou cerca de 4 núcleos e 8 GB sem recolha de logs e métricas. O quickstart do Compose pede pelo menos 2 GB, o que é suficiente para testes, mas deixa pouca margem para a base de dados de que outros serviços do sistema necessitarão.

O que acontece se eu perder a masterkey do Zitadel?

Tudo o que foi encriptado com ela permanece encriptado. As credenciais do fornecedor de identidade, a palavra-passe SMTP e as seeds de palavras-passe de uso único (OTP) não podem ser desencriptadas, e a chave não pode ser alterada posteriormente. Um dump da base de dados, por si só, não restaura uma instância funcional, pois o dump contém texto cifrado e nenhuma chave. Guarde a masterkey num gestor de palavras-passe, num local separado do backup que contém o dump. Se ambos se perderem, reconstruir a instância do zero é o único caminho restante.

Porque é que os e-mails de reposição de palavra-passe do Zitadel nunca chegam?

Porque nenhum fornecedor SMTP está configurado, ou o configurado não consegue entregar a mensagem. O Zitadel v4.20.0 utiliza o processamento de notificações legado por predefinição, pelo que as definições de três tentativas e cinco minutos do worker paralelo são ignoradas. Configure o fornecedor SMTP nas definições da instância e utilize o botão de teste no formulário, que envia uma mensagem real. Ative o fornecedor, utilize um relay autenticado numa porta permitida pelo seu fornecedor de VPS e publique registos SPF e DKIM para o domínio de envio, para que o e-mail não seja filtrado como spam.

Posso alterar o domínio externo do Zitadel após a instalação?

Sim, mas não apenas editando o .env. Altere o ZITADEL_EXTERNALDOMAIN, ZITADEL_EXTERNALPORT e ZITADEL_EXTERNALSECURE, e depois permita que o Zitadel execute novamente a sua fase de setup para que detete a alteração. As aplicações que já registou mantêm os seus antigos URIs de redirecionamento e têm de ser atualizadas manualmente; qualquer pedido cujo cabeçalho Host não corresponda a um domínio conhecido pelo Zitadel receberá um Instance not found. Escolher o nome final antes do primeiro arranque evita todo este processo.

Este artigo foi útil?