Base de Conhecimento

Keycloak na VPS: login único para seus sistemas

  • keycloak, login único, docker compose, nginx, postgresql
  • Usuários acharam útil: 0

Keycloak na VPS com Docker Compose, PostgreSQL, Nginx e HTTPS: o que são realm, client e usuário, como proteger o painel, fazer backup do banco e atualizar.

Por Redação Eleven Host · @robson.direitodigital · 6 de novembro de 2026 · 11 min de leitura

Arte da Eleven Host: janela de terminal com o título: Keycloak na VPS: login único para seus sistemas

Capa da Redação Eleven Host para o guia: Keycloak na VPS: login único para seus sistemas Arte: Eleven Host

Keycloak na VPS é o caminho para ter um login único para seus sistemas num servidor seu, com Docker Compose, PostgreSQL, Nginx e HTTPS. Veja o que é, como montar, proteger o painel, fazer backup e atualizar.

Atualizado em 06/11/2026. Na data deste guia, a 26.8.2, de 05/11/2026, é a versão mais nova listada. Os blocos de comando e de configuração são exemplos montados aqui: confira cada um no seu servidor antes de usar, e confira se saiu versão nova.

O que é o Keycloak e o que é login único

Segundo a página oficial, o Keycloak adiciona autenticação a aplicações e protege serviços. A ideia do login único é simples: o usuário se identifica no Keycloak, e não em cada sistema. Ele é de código aberto, sob a licença Apache-2.0, e adota os padrões OpenID Connect, OAuth 2.0 e SAML. A licença é só um dos pontos: servidor, domínio, manutenção e tempo continuam sendo custos seus.

Quatro termos aparecem no painel:

  • Realm: o espaço que reúne os usuários, as senhas, os papéis e os grupos de um conjunto de sistemas. A documentação compara com um inquilino (tenant).
  • Usuário: quem consegue entrar nos seus sistemas.
  • Client: um sistema seu, como um painel ou um aplicativo, que pede ao Keycloak para autenticar o usuário.
  • Realm master: o realm usado só para administrar o próprio Keycloak. Os seus sistemas ficam em outro realm, criado por você.

Se ainda está escolhendo o servidor, o guia completo de servidor VPS explica o que é uma VPS. Para ver como outros sistemas são instalados num servidor assim, há o guia de GLPI na VPS, sistema de chamados e o guia de Rocket.Chat na VPS, chat da equipe.

O Keycloak guarda as contas de quem entra nos seus sistemas. Se ele ficar fora do ar, os sistemas ligados a ele ficam sem novo login. A documentação descreve a produção típica com duas ou mais instâncias; numa VPS só, há uma instância, sem redundância.

Versão, memória e o que o tamanho da VPS precisa cobrir

Aqui, a imagem é quay.io/keycloak/keycloak:26.8.2, com a versão fixa na etiqueta, sem latest. No caminho com Docker, você não instala Java na VPS, porque a imagem já traz o que precisa. A 26.8.2 saiu com 33 correções de segurança com CVE, então trate a atualização como rotina.

Para contêiner, a documentação manda definir um limite de memória. Ela recomenda 2 GB de limite para implantações menores prontas para produção, e o Compose abaixo usa esse valor em mem_limit. Esse número vale para o contêiner do Keycloak, e não para a VPS: o PostgreSQL, o Nginx e o sistema ocupam memória por fora. A própria documentação pede testes de carga antes de entrar em produção.

start-dev, start e o banco

O comando start-dev é para experimentar o Keycloak pela primeira vez: liga HTTP, desliga a checagem estrita do hostname e usa um banco de desenvolvimento. A documentação diz que ele deve ser evitado em produção, por causa dos padrões inseguros. Em produção, o comando é start, que exige hostname e HTTPS (ou um proxy que faça o HTTPS) e um banco informado em KC_DB. O banco padrão, dev-file, é só para desenvolvimento.

Entre os bancos suportados estão PostgreSQL (14 a 18), MySQL e MariaDB; o exemplo usa o PostgreSQL 17. A documentação também descreve uma imagem otimizada com start --optimized, que evita o tempo extra de início; o exemplo usa start simples, por ter um passo a menos.

Vale olhar as opções de VPS antes de seguir? Confira na loja o que cada plano inclui. Ver as VPS

Passo 1: Docker e a pasta do projeto

Instale o Docker pela página oficial de instalação para Ubuntu, que traz o passo do repositório. O script de conveniência não é recomendado para produção. Um exemplo de comandos, depois de adicionar o repositório:

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo docker run hello-world

sudo mkdir -p /opt/keycloak

cd /opt/keycloak

sudo nano .env

sudo chmod 600 .env

Um exemplo do conteúdo do .env, com senhas fortes e diferentes entre si. Recomendamos evitar o caractere $ nas senhas, porque o Compose o interpreta:

POSTGRES_PASSWORD=troque-esta-senha-do-banco

KC_BOOTSTRAP_ADMIN_PASSWORD=troque-esta-senha-do-admin

Passo 2: o compose.yaml

Um exemplo de arquivo Compose, com o domínio fictício sso.exemplo.com.br. Salve como /opt/keycloak/compose.yaml. A indentação pode sumir ao copiar: o YAML depende dela, então confira os recuos.

services:

postgres:

image: postgres:17

restart: unless-stopped

environment:

POSTGRES_DB: keycloak

POSTGRES_USER: keycloak

POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

volumes:

- pgdata:/var/lib/postgresql/data

healthcheck:

test: ["CMD-SHELL", "pg_isready -U keycloak -d keycloak"]

interval: 10s

timeout: 5s

retries: 5

keycloak:

image: quay.io/keycloak/keycloak:26.8.2

command: start

restart: unless-stopped

mem_limit: 2g

depends_on:

postgres:

condition: service_healthy

environment:

KC_DB: postgres

KC_DB_URL_HOST: postgres

KC_DB_URL_DATABASE: keycloak

KC_DB_USERNAME: keycloak

KC_DB_PASSWORD: ${POSTGRES_PASSWORD}

KC_HOSTNAME: https://sso.exemplo.com.br

KC_HTTP_ENABLED: "true"

KC_PROXY_HEADERS: xforwarded

KC_BOOTSTRAP_ADMIN_USERNAME: tmpadm

KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_BOOTSTRAP_ADMIN_PASSWORD}

ports:

- "127.0.0.1:8080:8080"

volumes:

pgdata:

As variáveis, com os nomes da documentação:

  • KC_DB, KC_DB_URL_HOST, KC_DB_URL_DATABASE, KC_DB_USERNAME e KC_DB_PASSWORD configuram o banco.
  • KC_HOSTNAME fixa o endereço público em HTTPS.
  • KC_HTTP_ENABLED liga o HTTP interno; a documentação só admite HTTP em produção atrás de um proxy que faça o HTTPS, no caso o Nginx.
  • KC_PROXY_HEADERS com xforwarded faz o Keycloak confiar nos cabeçalhos X-Forwarded do Nginx.
  • KC_BOOTSTRAP_ADMIN_USERNAME e KC_BOOTSTRAP_ADMIN_PASSWORD criam o administrador temporário.

Suba os serviços e acompanhe o início. Um exemplo de comandos:

cd /opt/keycloak

sudo docker compose up -d

sudo docker compose logs -f keycloak

Porta só em 127.0.0.1 e o firewall

Publicar uma porta de contêiner é inseguro por padrão, segundo a documentação do Docker. Ela avisa que o Docker e o ufw são incompatíveis: o tráfego do contêiner é desviado antes das regras do ufw, e portas publicadas podem ignorar a sua configuração. Por isso o exemplo publica a 8080 só em 127.0.0.1, e só o próprio servidor, onde roda o Nginx, a alcança. Recomendamos não publicar o 5432 do banco, a 8443 nem a 9000, a interface de gerenciamento.

Passo 3: Nginx e HTTPS

Primeiro aponte o domínio para o IP da VPS, no painel de DNS de quem cuida dele. A documentação do Keycloak traz uma lista de caminhos que podem ou não ser expostos, e o exemplo de Nginx abaixo segue essa lista:

  • /realms/, /resources/ e /.well-known/: expostos, porque os sistemas e o navegador precisam deles.
  • /admin/ e /realms/master/: só para uso interno.
  • / inteiro, /metrics e /health: não expor. A porta 9000 também não passa pelo proxy.

A documentação também pede que o proxy sobrescreva os cabeçalhos de encaminhamento, em vez de apenas acrescentar, e remova os demais da lista dela. Por isso o exemplo não usa o modelo comum com $proxy_add_x_forwarded_for nem repassa o X-Real-IP. A documentação lista ainda cabeçalhos de rastreamento (como traceparent) a remover: confira a lista e acrescente o que faltar.

Um exemplo de comando e do arquivo /etc/nginx/snippets/keycloak-proxy.conf, para conferir no seu servidor:

sudo apt install nginx

sudo nano /etc/nginx/snippets/keycloak-proxy.conf

proxy_pass http://127.0.0.1:8080;

proxy_set_header Host $host;

proxy_set_header X-Forwarded-For $remote_addr;

proxy_set_header X-Forwarded-Proto $scheme;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Port $server_port;

proxy_set_header X-Forwarded-Prefix "";

proxy_set_header Forwarded "";

proxy_set_header X-Real-IP "";

proxy_set_header X-Original-Forwarded-For "";

proxy_set_header X-Original-URL "";

proxy_set_header X-Original-Method "";

proxy_set_header X-Forwarded-Access-Token "";

Um exemplo do site, em /etc/nginx/sites-available/sso.exemplo.com.br, ligado em sites-enabled. O 203.0.113.10 é um IP fictício: troque pelo IP fixo de onde você administra. Sem IP fixo, será preciso outra saída, como uma VPN, a testar antes. A indentação pode sumir ao copiar.

server {

listen 80;

server_name sso.exemplo.com.br;

location ^~ /admin/ {

allow 203.0.113.10;

deny all;

include snippets/keycloak-proxy.conf;

}

location ~ ^/realms/master(/|$) {

allow 203.0.113.10;

deny all;

include snippets/keycloak-proxy.conf;

}

location /realms/ { include snippets/keycloak-proxy.conf; }

location /resources/ { include snippets/keycloak-proxy.conf; }

location /.well-known/ { include snippets/keycloak-proxy.conf; }

location / { return 404; }

}

Depois, um exemplo de comandos para ativar o site e emitir o certificado com o Certbot, seguindo a página oficial dele (remova antes o pacote certbot do sistema, se existir). Se for usar o ufw, libere o SSH antes de ligá-lo:

sudo ln -s /etc/nginx/sites-available/sso.exemplo.com.br /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

sudo snap install --classic certbot

sudo ln -s /snap/bin/certbot /usr/local/bin/certbot

sudo certbot --nginx

sudo certbot renew --dry-run

sudo ufw allow OpenSSH

sudo ufw allow 'Nginx Full'

sudo ufw enable

Primeiro acesso e o admin temporário

Em contêiner, o Keycloak só permite criar o primeiro administrador por conexão local, e por isso o Compose define o admin temporário. Abra https://sso.exemplo.com.br/admin/ a partir do IP liberado e entre com tmpadm.

Essa conta é temporária: o console mostra um aviso, e ela só é criada no primeiro início. Crie logo um administrador permanente no realm master e remova a conta temporária, porque a remoção é manual.

Em seguida, crie o seu realm e o primeiro sistema. Os nomes das telas estão em inglês; confira na 26.8.2:

  • Manage realms, depois Create realm, para o espaço dos seus sistemas.
  • Users, depois Create new user; em Credentials, defina a senha e desligue Temporary.
  • Clients, depois Create client: tipo OpenID Connect, fluxo Standard flow, com os campos Valid redirect URIs e Web origins do sistema.

Backup do banco e restauração

O backup de verdade é o do banco, e a documentação manda copiá-lo antes de atualizar. A exportação de um realm tem limitações como backup: eventos, sessões persistidas e tokens revogados não saem nela. Um exemplo de comandos com pg_dump e a restauração:

cd /opt/keycloak

sudo sh -c 'docker compose exec -T postgres pg_dump -U keycloak -Fc keycloak > keycloak-$(date +%F).dump'

sudo docker compose stop keycloak

sudo sh -c 'docker compose exec -T postgres pg_restore -U keycloak -d keycloak --clean --if-exists < keycloak-AAAA-MM-DD.dump'

sudo docker compose start keycloak

Troque AAAA-MM-DD pela data do arquivo. Guarde também o .env, o compose.yaml e a configuração do Nginx, e copie tudo para fora da VPS. O dump contém dados de usuários e credenciais: guarde com o mesmo cuidado do banco. Recomendamos ensaiar a restauração num servidor de teste.

Atualização

A documentação de atualização começa por ler as mudanças desde a sua versão. Por padrão, o banco é migrado sozinho no primeiro início da versão nova, e o Keycloak não reverte essas mudanças: para voltar, restaure a instalação antiga e depois o banco, a partir da cópia. Voltar só a etiqueta da imagem não desfaz a migração. Em versões menores e maiores, o servidor precisa parar, e com uma instância só o login fica fora durante a troca.

Um exemplo de passos: backup do banco, leitura das mudanças, troca da etiqueta no compose.yaml e estes comandos:

sudo docker compose pull

sudo docker compose up -d

sudo docker compose logs -f keycloak

Onde ver os planos de VPS

A loja da Eleven Host reúne as VPS disponíveis.

Dá para comparar os planos de VPS com calma? Confira na loja o que cada plano inclui. Ver os planos de VPS

Perguntas frequentes

Posso usar o start-dev em produção?

Não. A documentação diz que ele deve ser evitado em produção, por causa dos padrões inseguros. Use start, com banco externo, hostname e HTTPS.

Preciso instalar Java na VPS?

No caminho com Docker, não: a imagem oficial já inclui o que precisa. Java só entra na instalação direta, sem contêiner.

O export do realm serve como backup?

Não como backup completo. A própria documentação aponta limitações, e o backup do banco continua sendo o principal.

Posso deixar o painel de administração aberto na internet?

A documentação desaconselha expor o / inteiro e trata /admin/ e /realms/master/ como caminhos só internos. Recomendamos restringir o acesso, como no exemplo do Nginx.

Esta resposta lhe foi útil?

Artigos Relacionados