Instalação rápida com Docker Compose

A forma mais rápida de rodar o Keycloak localmente é com Docker Compose. Tempo estimado: menos de 5 minutos.

Crie o arquivo `docker-compose.yml`

docker-compose.yml — desenvolvimento

services:
  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start-dev
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"

O modo start-dev usa banco H2 em memória — ideal para testes locais, mas não para produção.

Suba o container

Terminal

docker compose up -d

Aguarde o Keycloak inicializar. Você pode acompanhar os logs com docker compose logs -f keycloak.

Acesse o Admin Console

Navegador

http://localhost:8080/admin
# usuário: admin | senha: admin

Instalação com PostgreSQL (recomendado)

Para ambientes além do desenvolvimento local, use PostgreSQL como banco de dados. O banco H2 padrão não persiste dados entre reinicializações.

docker-compose.yml — com PostgreSQL

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak_senha_forte
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start-dev
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin_senha_forte
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak_senha_forte
    ports:
      - "8080:8080"
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:

Variáveis de ambiente principais

Variável	Descrição	Padrão
KEYCLOAK_ADMIN	Usuário do console administrativo	—
KEYCLOAK_ADMIN_PASSWORD	Senha do usuário administrativo	—
KC_DB	Tipo do banco: `postgres`, `mysql`, `mariadb`, `mssql`	dev-mem
KC_DB_URL	JDBC URL de conexão com o banco	—
KC_HOSTNAME	Hostname público do Keycloak (produção)	—
KC_HOSTNAME_STRICT	Rejeita requisições com hostname diferente	true
KC_PROXY	Modo de proxy reverso: `edge`, `reencrypt`, `passthrough`	none
KC_HTTP_ENABLED	Habilita HTTP (necessário atrás de proxy HTTPS)	false
KC_LOG_LEVEL	Nível de log: `INFO`, `DEBUG`, `WARN`	INFO

Checklist para produção

✓Use PostgreSQL ou MySQL — nunca o banco H2 padrão em produção
✓Configure HTTPS — o Keycloak não deve ser exposto sem TLS; use Nginx ou Traefik como proxy reverso
✓Defina KC_HOSTNAME corretamente — deve ser o domínio público real do Keycloak
✓Senhas fortes — KEYCLOAK_ADMIN_PASSWORD e KC_DB_PASSWORD devem ser geradas aleatoriamente
✓Use secrets — não coloque credenciais diretamente no docker-compose.yml; use Docker Secrets ou um vault
✓Backup do banco — configure backup periódico do PostgreSQL; todos os dados de usuários ficam lá
⚠start-dev vs start — em produção use start, nunca start-dev, que desativa validações de segurança
⚠Limit Admin Console access — restrinja o acesso à rota /admin por IP no proxy reverso

Nginx como proxy reverso

O Keycloak em produção deve rodar atrás de um proxy que termina o TLS. Exemplo mínimo com Nginx:

nginx.conf (trecho)

server {
  listen 443 ssl;
  server_name auth.empresa.com.br;

  ssl_certificate     /etc/ssl/cert.pem;
  ssl_certificate_key /etc/ssl/key.pem;

  location / {
    proxy_pass http://keycloak:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

No Keycloak, defina:

Variáveis adicionais

KC_PROXY: edge
KC_HTTP_ENABLED: "true"
KC_HOSTNAME: auth.empresa.com.br

Links úteis para aprofundar

⚙️

Guia oficial de configuração

Todas as opções de configuração do servidor Keycloak.

→ 🚧

Running Keycloak in a container

Documentação oficial para deploy em Docker e Kubernetes.

→ 💾

Configuração de banco de dados

PostgreSQL, MySQL, MariaDB e SQL Server com Keycloak.

→ 🌐

Usando proxy reverso

Nginx, Apache, AWS ALB, Traefik — configuração detalhada.

→

Implementação profissional

Prefere deixar a instalação com quem já fez isso antes?

A Solis cuida de toda a instalação, configuração e integração do Keycloak — inclusive em ambientes com alta disponibilidade, múltiplos nodes e requisitos regulatórios.

✓ Instalação em produção com HA e PostgreSQL
✓ Integração com Active Directory e sistemas existentes
✓ Treinamento da equipe técnica

Falar com especialistas →

Como instalar o Keycloak