Setting up a database for Keycloak may sound complex, but it’s actually very simple once you know the right steps. In this blog, we’ll walk through the process of configuring a database for Keycloak and running it for the first time. This guide is tailored for beginners who want to quickly get started with Keycloak using its built-in configuration files.

Step 1: Navigate to the Configuration File

When you download and extract Keycloak (for example, version 26.3.4), you’ll find a folder structure like this:

keycloak-26.3.4/
   ├── bin/
   ├── conf/
   ├── lib/
   └── ...

Inside the conf folder, you’ll find a file named keycloak.conf.

This file is where Keycloak reads its database configuration details.

The path looks like this:

\keycloak-26.3.4\conf\keycloak.conf

Step 2: Open and Edit keycloak.conf

Open the keycloak.conf file in your preferred text editor (Notepad, VS Code, or any IDE).

Here, you can specify database details if you’re connecting to an external database (like PostgreSQL or MySQL). But if you’re just starting out and want Keycloak to automatically create its database, you don’t need to make changes. Keycloak will use the default configuration and set it up for you.

Step 3: Run the Start Command

Now, it’s time to launch Keycloak.

1. Open Command Prompt (CMD).
2. Navigate to the bin folder inside your Keycloak directory:

cd keycloak-26.3.4\bin

Run the following command:

./kc.sh start-dev

This tells Keycloak to start in development mode. In this mode, Keycloak automatically sets up the necessary database tables for you.

Step 4: Database Creation Happens Automatically

When you run the ./kc.sh start-dev command:

• Keycloak connects to the default database (by default, it uses an embedded H2 database).
• It automatically creates all required tables needed for users, roles, clients, sessions, and tokens.
• You don’t have to manually create the schema or run SQL scripts.

This makes it perfect for testing, learning, or experimenting with Keycloak.

Step 5: Verify Setup

Once Keycloak starts, you should see logs in the terminal indicating that the server is running on http://localhost:8080/.

• Open your browser and go to http://localhost:8080.
• You’ll see the Keycloak welcome page.
• From here, you can log in, configure realms, and start managing authentication and authorization.