Deploy Keycloak in one click

What is Keycloak?

Keycloak is an identity and access management server: your apps hand sign-in to it, and a person who has signed in once is signed in to all of them. It speaks OpenID Connect, OAuth 2.0 and SAML 2.0, so most apps and frameworks connect to it with their standard libraries. It signs people in with a password, a passkey or a social account such as Google or GitHub, adds two-factor authentication with one-time codes, syncs users from LDAP and Active Directory, and lets each user manage their profile, password and sessions in its account console.

Keycloak is a Cloud Native Computing Foundation incubation project, used by companies and home labs alike to put one sign-in in front of many apps. This template runs it in production mode with PostgreSQL behind the proxy, and makes the administrator of the master realm from the fields before Keycloak answers anyone. The catch: Keycloak is powerful and has many settings, so a first client takes some reading, and it runs on Java, which takes more memory than most sign-in servers.

Hosting Keycloak on Pethost

1. You sign in to Pethost with a passkey, GitHub or Google. No machine yet? You pick a plan, and the link waits until it is ready.
2. New project opens at Keycloak. You fill in what it asks for and click Create project: Username, Admin password.
3. In a minute or two Keycloak is live at its own address with HTTPS. Its secrets are made at random, and its data is in the nightly backup.
4. It is a project like any other: you or your agent can change it, roll it back or restore it.

Questions about Keycloak

Keycloak Docker Compose file

The template is this compose.yaml and the variables written into the project’s .env as it is created. Pethost runs the file as it is written.

Containers: keycloak (quay.io/keycloak/keycloak:26.8), postgres (postgres:18-alpine).

Volumes, in the nightly backup: db.

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.8
    restart: unless-stopped
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ${POSTGRES_PASSWORD}
      KC_HOSTNAME: ${URL}
      # The proxy serves HTTPS and passes requests on over HTTP, saying in X-Forwarded-* who sent
      # them and how.
      KC_HTTP_ENABLED: "true"
      KC_PROXY_HEADERS: xforwarded
      KC_HEALTH_ENABLED: "true"
      # The administrator of the master realm is made from these at the first start, before
      # Keycloak answers anyone; Keycloak calls it temporary until a permanent one replaces it.
      KC_BOOTSTRAP_ADMIN_USERNAME: ${ADMIN_USERNAME}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
    depends_on:
      postgres:
        condition: service_healthy
    # The port listens before Keycloak is ready: the deploy waits for its readiness, which its
    # management port answers. The image has no curl: bash asks it.
    healthcheck:
      test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/9000 && printf 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && grep -q '\"UP\"' <&3"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 180s

  postgres:
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - db:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U keycloak -d keycloak"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 30s

volumes:
  db:

compose.yamlSee it on GitHub