Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Concepts and Setup

Installing Keycloak from the Distribution (ZIP, Java, kc.sh)

Install Keycloak without Docker: Java requirements, download and unpack, the kc.sh and kc.bat commands, start-dev versus start, build, and a first start checklist.

Containers are convenient, but plenty of teams run Keycloak straight on a virtual machine or a laptop. The server is a plain Java application, and installing it is just "unpack and run". This lesson covers that path: prerequisites, the folder layout, the kc command and its sub-commands, and what changes between development and production starts.

Everything here happens on your own machine; the site cannot run Keycloak. The runnable blocks are stand-ins: a Java version checker and a command planner that teach the rules without needing a server.

Prerequisites

  • Java. Keycloak 26 needs a current long-term-support JDK (Java 21 is the usual choice; check the "Getting started" page of your version for the exact minimum). The java -version command must report it.
  • A database for production. Development mode embeds H2. Production uses PostgreSQL, MariaDB, MySQL, Oracle or SQL Server (PostgreSQL is the most common).
  • Memory. Plan for at least 2 GB of RAM for a small installation.
  • Ports. 8080 (HTTP) and 8443 (HTTPS) by default, plus 9000 for management (health and metrics).

Download and unpack

Get the ZIP or TAR.GZ file named keycloak-26.x.y from the official download page, then:

Terminal
unzip keycloak-26.4.0.zip
cd keycloak-26.4.0

You will see these folders:

Folder Contents
bin/ The kc.sh (Linux, macOS) and kc.bat (Windows) launchers, plus kcadm and kcreg command-line clients
conf/ keycloak.conf (your configuration), truststores and similar
data/ H2 files, import/export folders, temporary files
lib/ The application and its build output
providers/ Drop-in custom extensions (SPI JAR files)
themes/ Custom themes
version.txt The exact version

Create the first admin

Set the bootstrap admin through environment variables before the first start:

Terminal
export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD='pick-a-long-passphrase'

On Windows PowerShell use $env:KC_BOOTSTRAP_ADMIN_USERNAME = "admin" and call bin\kc.bat. Alternatively open the server in development mode and the welcome page asks you to create the first admin from a browser on the same machine.

The kc command

Terminal
bin/kc.sh start-dev

That is all you need for a development server on http://localhost:8080. The launcher has several sub-commands:

Command Does
start-dev Start in development mode
start Start in production mode (needs hostname, HTTPS or a proxy, a real database)
build Apply build-time options once, so later starts are fast
start --optimized Start without re-running the build step
export / import Dump or load realms as JSON files
show-config Print the effective configuration, with value sources
bootstrap-admin Create a temporary admin user from the command line
--help Help for any command, for example bin/kc.sh start --help --verbose

Build-time versus run-time options

Keycloak is built on Quarkus, which optimizes the application at build time. Some options are fixed by that build, others can change on every start.

  • Build-time options: database vendor (db), enabled features (features), health and metrics endpoints, the cache type, the transaction type, and your custom providers.
  • Run-time options: hostname, HTTP ports, the database URL, user name and password, logging, proxy settings, TLS certificate files.

The recommended production pattern is two steps (often in a Dockerfile):

Terminal
bin/kc.sh build --db=postgres --health-enabled=true --metrics-enabled=true
bin/kc.sh start --optimized \
  --hostname=https://id.example.com \
  --db-url=jdbc:postgresql://db:5432/keycloak \
  --db-username=keycloak --db-password="$DB_PASSWORD"

If you pass a build-time option to a plain start that differs from the last build, Keycloak rebuilds automatically, which takes extra seconds at every start. --optimized skips that and fails fast when options conflict.

Production start requirements

bin/kc.sh start refuses to run unless you provide:

  1. A hostname (--hostname), the public URL users and apps will see.
  2. HTTPS (--https-certificate-file and --https-certificate-key-file, or a Java keystore) or, behind a TLS-terminating proxy, --http-enabled=true plus proxy settings.
  3. A database other than embedded H2 (recommended; H2 is for development).

These are discussed in Configuring the Keycloak Server and in the deployment chapter.

A Java version check (stand-in)

Most failed first starts are "wrong Java". This stand-in parses the first line of java -version output and tells you whether it meets a minimum.

Node.js Stand-in: is my Java new enough?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A start-command planner (stand-in)

This stand-in decides which kc.sh commands you should run for a goal, and flags a production plan that lacks something essential.

Node.js Stand-in: plan the kc.sh commands

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

First-start checklist

  1. java -version shows the supported LTS.
  2. The bootstrap admin variables are set (for a fresh database).
  3. Ports 8080 and 9000 are free.
  4. You use start-dev for learning and build + start --optimized for real.
  5. Open http://localhost:8080/admin/, sign in, and create your own realm.

If you later move to production, you do not lose your learning data: realms can be exported with bin/kc.sh export --dir /tmp/export and imported elsewhere with import, as covered in the operations chapter.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which folder holds custom provider (SPI) JAR files?

    Copy extension JARs into providers/ and run a build so they are picked up.
  2. 2. What is the benefit of kc.sh build followed by kc.sh start --optimized?

    Quarkus optimizes the application at build time; running that step once avoids repeating it at every start.
  3. 3. Which of these is a build-time option?

    The database vendor changes which drivers and code are built in. Hostname, ports and credentials can change at start-up.
  4. 4. What does kc.sh start require in addition to start-dev?

    Production mode is strict by design so insecure defaults are not used by accident.

Summary

  • Keycloak is a Java application: install a supported LTS JDK, unpack the ZIP and run bin/kc.sh (or kc.bat).
  • Folders: bin, conf, data, lib, providers, themes.
  • start-dev is for learning; start needs a hostname, HTTPS or proxy settings and a real database.
  • Use build once and start --optimized afterwards; know which options are build-time.
  • export and import move realms between servers.

Next: Configuring the Keycloak Server