Keycloak na VPS: login único para seus sistemas
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

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_USERNAMEeKC_DB_PASSWORDconfiguram o banco.KC_HOSTNAMEfixa o endereço público em HTTPS.KC_HTTP_ENABLEDliga 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_HEADERScomxforwardedfaz o Keycloak confiar nos cabeçalhosX-Forwardeddo Nginx.KC_BOOTSTRAP_ADMIN_USERNAMEeKC_BOOTSTRAP_ADMIN_PASSWORDcriam 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,/metricse/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.