Learn Keycloak - Installing Keycloak

#Introduction

In episode 18 you mastered groups and roles as the authorization foundation. Episode 19 marks the move from theory to practice: installing Keycloak for the first time. You'll look at the ZIP/TAR method, the Docker container, all the way to Kubernetes, choose the right database, create the first admin, and understand the distribution directory structure.

#Choosing an Installation Method

#Standalone (ZIP/TAR)

The most classic method: download the ZIP or TAR archive from the official Keycloak site, extract it, then run the script in the bin folder.

cd keycloak-<versi>
bin/kc.sh start-dev

This method suits labs and development machines. Here you get acquainted directly with kc.sh and the whole distribution structure.

#Docker Container

For a single production server, the Docker container is the most common choice:

docker run --name keycloak -p 8080:8080 \
  quay.io/keycloak/keycloak:latest \
  start-dev

Note the registry: quay.io/keycloak/keycloak is the official location of the Keycloak image, not Docker Hub. On first access, Keycloak will ask you to create an admin account via the web page.

#Kubernetes (Keycloak Operator)

On a Kubernetes cluster, the best way is the Keycloak Operator, which manages Keycloak instances and realm imports through CRDs (Custom Resource Definitions):

Declaring Keycloak via the operator

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: keycloak
spec:
  instances: 2
  hostname:
    hostname: id.example.com

The operator handles rolling updates, health checks, and horizontal scaling — far tidier than managing pods manually.

#Cloud Deployments (AWS, GCP, Azure)

In the cloud, the principles are the same as above: the same image, a managed database, and a load balancer terminating TLS. The main difference is only in how secrets are stored and how network policies are set.

#Method Comparison

#Development vs Production Mode

#start-dev

bin/kc.sh start-dev starts the server with many safeguards disabled: HTTPS not required, loose hostname, built-in H2 database. Its single purpose: ease learning. Don't use it in production.

bin/kc.sh start-dev

#Production Mode

bin/kc.sh start --hostname id.example.com \
  --https-port 8443 \
  --db postgres

Production mode requires --hostname and HTTPS; without them the server refuses to run. kc.sh start --prod sets production mode and enforces those requirements at once.

#Parameters vs Environment Variables

Every --xxx option has an KC_XXX environment variable counterpart. For example --http-port becomes KC_HTTP_PORT. Which one you use is up to you — they're equivalent; environment variables are more practical in Docker.

#Database Configuration

#H2 — Development Only

By default Keycloak uses the embedded H2 database. Data is stored locally in the data directory, is easy to lose, and isn't a choice for production.

#PostgreSQL — Recommended

For production, PostgreSQL is the most common choice. Configure it via environment variables:

Connecting to PostgreSQL via environment variables

KC_DB=postgres
KC_DB_URL=jdbc:postgresql://db.example.com:5432/keycloak
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=rahasia

KC_DB selects the database type, KC_DB_URL contains the full JDBC URL, and KC_DB_USERNAME plus KC_DB_PASSWORD configure the connection credentials.

#MySQL/MariaDB, Oracle, MSSQL

Besides PostgreSQL, Keycloak supports MySQL/MariaDB, Oracle, and SQL Server. Some databases need a JDBC driver placed in the providers folder; make sure the driver is available before starting.

#Database Migration

When upgrading versions, Keycloak performs schema migration automatically as long as the connection configuration remains the same. Always back up the database before an upgrade — a migration failing halfway is much easier to recover with a backup.

#Database Comparison

#Initial Setup

#Creating the Admin User

On the first run, visit the server address and the admin creation page will appear (username and password). Or set it before the first start via environment variables: recent releases use KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD, while older releases use KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD.

#Master Realm

The first realm created is named master. Its role is special: managing Keycloak itself. Don't put your applications here.

#Creating a New Realm

Create a new realm (for example myrealm) for your applications. Login users and application clients live in this realm, separated from master, so administration and policy settings don't mix.

#Basic Configuration

Adjust the realm's display name, enable the login features needed, and make sure the database configured earlier is at the right point. Realm configuration details will be dissected in episode 20.

#Directory Structure

After extraction, you'll find these important folders:

Understanding this structure helps you know where to inject configuration, themes, and custom providers.

#Closing

In episode 19, you installed Keycloak: choosing a method (ZIP/TAR, Docker from quay.io, the Kubernetes operator, or cloud), distinguishing development and production modes, configuring the database (H2, PostgreSQL, MySQL/MariaDB, Oracle/MSSQL), performing the initial setup (admin user, master realm, new realm), and learning the directory structure.

Key takeaways:

• start-dev for learning, start --prod for production — don't mix them up.
• PostgreSQL is the safe choice for production; H2 is only for labs.
• master realm for administration, your own realm for applications.
• --hostname and HTTPS are mandatory in production; without them the server refuses to run.

In the next episode (episode 20), you'll tune the instance you just installed: Keycloak Configuration — realm settings, client settings, authentication flows, and password policies.