lzocateli/keycloak repository overview

⁠Keycloak 26.7.0

Keycloak 26.7.0 configuravel em runtime para PostgreSQL ou Microsoft SQL Server. Health e metricas ficam habilitados por padrao na porta de gerenciamento 9000.

⁠Referencia da imagem

Esta imagem preserva a distribuicao padrao, sem executar kc.sh build para um vendor especifico. Isso permite selecionar postgres ou mssql no runtime, ao custo de uma etapa de configuracao no primeiro startup. Para cargas maiores, produza uma variante otimizada e exclusiva para o banco escolhido.

⁠Compatibilidade dos bancos do repositorio

Verificacao realizada com a matriz oficial do Keycloak 26.7.0:

SQL Server 2025 pode funcionar com o driver mssql incluido, mas fica fora da matriz suportada pelo Keycloak. Para producao com suporte do fornecedor, use PostgreSQL 18.4 deste repositorio ou uma versao SQL Server suportada. Azure SQL Database e Azure SQL Managed Instance latest aparecem separadamente como suportados e nao tornam SQL Server 2025 local uma configuracao suportada.

Fonte: https://www.keycloak.org/server/db.

Smoke tests executados nesta atualizacao:

O smoke test com SQL Server 2025 demonstra compatibilidade funcional neste cenario, mas nao substitui suporte oficial nem valida upgrades, extensoes ou cargas de producao.

⁠Configuracao comum

Crie .env a partir de .env.example, substitua todos os valores de senha e ajuste KC_HOSTNAME para a URL publica.

Se uma senha contiver $ ou ${...}, use KCRAW_DB_PASSWORD no lugar de KC_DB_PASSWORD para preservar o valor literal.

⁠Docker Compose com PostgreSQL 18.4

Esta e a combinacao recomendada entre as imagens atuais do repositorio:

services:
  postgres:
    image: lzocateli/postgresql:18.4-pgvector0.8.5-bookworm
    environment:
      POSTGRES_USER: ${KC_DB_USERNAME}
      POSTGRES_PASSWORD: ${KC_DB_PASSWORD}
      POSTGRES_DB: keycloak
    volumes:
      - ./data/postgres:/var/lib/postgresql
    healthcheck:
      test: ["CMD", "postgresql-healthcheck"]
      start_period: 30s
      interval: 10s
      timeout: 5s
      retries: 6

  keycloak:
    image: lzocateli/keycloak:26.7.0
    command: ["start"]
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: ${KC_BOOTSTRAP_ADMIN_USERNAME}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_BOOTSTRAP_ADMIN_PASSWORD}
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: ${KC_DB_USERNAME}
      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
      KC_HOSTNAME: ${KC_HOSTNAME}
      KC_HTTP_ENABLED: "true"
      KC_PROXY_HEADERS: xforwarded
    ports:
      - "127.0.0.1:8080:8080"
    mem_limit: 2g

O caminho ./data/postgres e relativo ao diretorio do arquivo Compose. Crie essa pasta antes da primeira execucao e inclua-a na rotina de backup. No PostgreSQL 18, mantenha o destino /var/lib/postgresql; o cluster e criado no subdiretorio versionado /var/lib/postgresql/18/docker.

⁠Docker Compose com SQL Server 2025 CU7

O exemplo abaixo e experimental porque SQL Server 2025 nao consta na matriz suportada pelo Keycloak 26.7.0:

services:
  mssql:
    image: lzocateli/mssql-server:2025-CU7-ubuntu-24.04
    platform: linux/amd64
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_PID: ${MSSQL_PID:-Developer}
      MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD}
      MSSQL_DATABASE: keycloak
      MSSQL_DATABASE_COLLATE: Latin1_General_100_CI_AS_SC_UTF8
      MSSQL_USER: ${KC_DB_USERNAME}
      MSSQL_PASSWORD: ${KC_DB_PASSWORD}
    volumes:
      - ./data/mssql:/var/opt/mssql

  keycloak:
    image: lzocateli/keycloak:26.7.0
    command: ["start"]
    restart: unless-stopped
    depends_on:
      mssql:
        condition: service_healthy
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: ${KC_BOOTSTRAP_ADMIN_USERNAME}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_BOOTSTRAP_ADMIN_PASSWORD}
      KC_DB: mssql
      KC_DB_URL: "jdbc:sqlserver://mssql:1433;databaseName=keycloak;encrypt=true;trustServerCertificate=true"
      KC_DB_SCHEMA: dbo
      KC_DB_USERNAME: ${KC_DB_USERNAME}
      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
      KC_HOSTNAME: ${KC_HOSTNAME}
      KC_HTTP_ENABLED: "true"
      KC_PROXY_HEADERS: xforwarded
    ports:
      - "127.0.0.1:8080:8080"
    mem_limit: 2g

trustServerCertificate=true serve apenas ao certificado autoassinado do exemplo local. Em producao, valide a cadeia e a identidade do servidor. Antes de iniciar o Keycloak, habilite o isolamento recomendado:

ALTER DATABASE [keycloak] SET READ_COMMITTED_SNAPSHOT ON;

⁠Desenvolvimento com Podman e tema customizado

Nao monte o /tmp do host no container. O Keycloak cria os arquivos temporarios necessarios em seus diretorios gravaveis, e esse conteudo nao deve ser persistido. A montagem antiga -v /tmp:/tmp era desnecessaria e ainda expunha arquivos temporarios de outros processos do host ao container.

Para personalizar a tela de login, monte somente o diretorio do seu tema, sem substituir todo o /opt/keycloak/themes. Por exemplo:

themes/minha-marca/
└── login/
    ├── theme.properties
    └── resources/
        ├── css/styles.css
        └── img/logo.svg

O arquivo themes/minha-marca/login/theme.properties pode comecar com:

parent=keycloak
styles=css/styles.css

No CSS, referencie o logo como url('../img/logo.svg'). Em um template FreeMarker, use <img src="${url.resourcesPath}/img/logo.svg" alt="Logo">. Execute o ambiente de desenvolvimento com banco H2 efemero e cache de temas desabilitado:

docker run --rm --replace \
  --name keycloak-dev \
  --publish 127.0.0.1:8080:8080 \
  --env KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  --env KC_BOOTSTRAP_ADMIN_PASSWORD='Troque_Esta_Senha_Administrativa_2026!' \
  --volume ./themes/minha-marca:/opt/keycloak/themes/minha-marca:ro,Z \
  lzocateli/keycloak:26.7.0 \
  start-dev \
    --spi-theme--static-max-age=-1 \
    --spi-theme--cache-themes=false \
    --spi-theme--cache-templates=false

Acesse http://localhost:8080/admin, selecione o realm e escolha minha-marca em Realm settings > Themes > Login theme. Edicoes em CSS, imagens e templates ficam disponiveis ao atualizar a pagina. Em hosts sem SELinux, remova ,Z da opcao de volume.

O bind mount e adequado para desenvolvimento. Em producao, reative o cache e distribua o tema como artefato versionado, preferencialmente um JAR instalado em /opt/keycloak/providers, especialmente quando houver mais de uma instancia.

⁠Producao e proxy

• Use start, nunca start-dev, em producao.
• Termine TLS no proxy reverso ou configure HTTPS diretamente no Keycloak.
• Nao publique a porta de gerenciamento 9000; exponha-a apenas para health checks e coleta interna de metricas.
• Defina limite de memoria. A recomendacao inicial para uma instancia pequena de producao e 2 GiB.
• Restrinja a porta do banco a uma rede interna.
• Use secrets do orquestrador ou o Keycloak Config Keystore em vez de versionar senhas.
• Faca backup do banco antes de atualizar; migrations de schema ocorrem no startup.

O health check consulta /health/ready na porta interna 9000. A aplicacao atende HTTP em 8080 quando KC_HTTP_ENABLED=true; HTTPS direto usa 8443.

⁠Build local

docker buildx build --check --file keycloak/Dockerfile keycloak
docker buildx build \
  --pull \
  --platform linux/amd64 \
  --tag lzocateli/keycloak:26.7.0 \
  --load \
  keycloak

⁠Validacao

docker run --rm lzocateli/keycloak:26.7.0 --version
docker image inspect lzocateli/keycloak:26.7.0

Antes da publicacao, valide startup, readiness, conexao e migrations com o banco escolhido. Execute tambem Trivy, SBOM e proveniencia pelo workflow oficial.

⁠Tags e atualizacao

Nao sobrescreva a tag. Para atualizar, publique uma nova versao e teste providers, temas, clients, realms e rollback de banco em ambiente isolado.

⁠Troubleshooting

⁠Licencas e fontes

O badge MIT descreve apenas o conteudo original deste repositorio. Componentes de terceiros permanecem sujeitos aos termos de suas fontes. Consulte a politica de licenciamento⁠.

⁠Historico de alteracoes

• 26.7.0: atualiza a base, fixa digest linux/amd64, habilita health/metricas e documenta PostgreSQL 18.4 e SQL Server 2025 CU7.